Gold Medal Software 3/Gold Medal Software - Volume 3 (Gold Medal) (1994).iso/wordproc/hshell1.arj/HSREF.HYP/hsref.hxp

Text File | 1993-12-29 | 200KB | 5,790 lines

.INDEX
.HEADER
~M ~TwF~TKile ~PMFile~Kf~E ~M ~TwC~TKontents ~PMContents~Kc~E ~M ~TwG~TKoto ~PMGoto~Kg~E ~M ~TwS~TKearch ~PMSearch~Ks~E ~M ~TwO~TKther ~PMOther~Ko~E ~M ~TwH~TKelp ~PMHelp~Kh~E ~c
║~A    ~PF-~K-~E║~A    ~PB~E║~A   ~Pb@B~E║~A    ~PF+~K+~E║~A   ~PA@C3$$1~E║
┌──────────────────────────────────────────────────────────────────────────────┐
│~DF $1 - $2 ~h/~C72√ Match~Z~C79 ~DT│
└──────────────────────────────────────────────────────────────────────────────┘~i5
.REMARK
Reference hyperfile for HyperShell
Copyright (c) 1990,1991,1992 N.G.Taylor
Version 4 amendment level 9
.
.PRINT MARGIN 5
.
.PRINT TITLE
HyperShell Reference Guide
.
.CHECK +fa
Check both menu types

.
.MENU File
Type file  |T?File name
List HSREF |O91;THSREF.HYP;O90
──── » ────|ZUc
Command    |D?Command line
DOS shell  |D
──── « ────|ZUh
About     a|NHyperShell
Quit  F10 q|Q
.
.MENU Search
Title search   |A@S?Search string
Search Text  F6|A@X?Search string
Pick and search|SPicksrch
─────── » ─────|ZUo
Add to search  |O*64;MSearch
Refine search  |O*63;MSearch
─────── « ─────|ZUg
Matched flag ± |ZL/
───────────────|
Next matching  |F+1
List matching l|A@C1
Unmatched list |A@C2
.
.MENU Contents
Contents list F2|A@C
─────── » ──────|ZUg
From current    |A@C3$1
Starting with   |A@C0?Starting with
────── « ───────|ZUf
List sections   |A@C4Section
By category     |MCategories
.
.MENU Categories
Action codes    |A@C4Action
Conditions      |A@C4Condition
Function codes  |A@C4Function
Modifier codes  |A@C4Modifier
Reference flags |A@C4Flag
Dynamic menus   |A@C4Menuspec
Bitmap commands |A@C4Sublanguage
Graphic system  |A@C4^\[G\]
.
.MENU Goto
Next frame        n|F+
Matching frame    m|F+1
Previous frame    p|F-
Home frame         |b1
 ─────── » ─────── |ZUs
Backtrack one     b|B
Unwind backtrack F4|b@B
Revisit frame      |A@b
 ─────── « ─────── |ZUc
Select noted ref F5|A@R
.
.MENU Other
Action    F8|A?What action
Calculator  |SCalculator
───── » ────|ZUh
Example     |FExample script
Print frame |Dhp -p -o hsref $1
───── « ────|ZUs
Set colours |MColours;y#
Last error  |Sperror
.
.MENU Help
Selecting    |NSelecting
Key mappings |NKey mappings
Funct. keys  |NFkeys
Menu bar     |NMenu bar
────── » ────|ZUf
Information i|NInfo
Notation     |NNotation
Colour key   |NKey
────── « ────|ZUo
Paged lists  |MPaged Help

.
.MENU Paged Help
Control Keys |NPaged control keys
Paged lists  |NPaged lists
Selecting    |NSelecting
.
.CHECK -fax
.
.MENU Error text
1 - Operation cancelled
2 - No selection from menu
3 - End of file
4 - Cant open file
5 - File not open
6 - File open
7 - File changed
8 - At start of backtrack
9 - Divide by 0
10 - Value not expected
11 - Value expected
12 - Undefined opcode
13 - Unmatched parenthesis
14 - Syntax error
15 - Script not available
16 - Menu not available
17 - Note not available
18 - Frame not available
19 - Key not defined
20 - Invalid key code
21 - Local ref can't be noted
22 - Not at reference
23 - Key not mapped
24 - No action or disabled
25 - Invalid action code
26 - No command
27 - Env var not present
28 - Invalid dynamic menu
29 - Line too wide for screen
30 - String too long
31 - Too many lines in frame
32 - Max script reached
33 - Maximum menu size reached
.
.NOTE HyperShell
  -------------- HyperShell Version 5 --------------
      Copyright (c) Text Technology 1988-1993
Design, Implementation and Documentation by Nick Taylor
.
.NOTE Paged lists
 Type contents of file
 Search titles or texts
 Detailed directory list
 Contents list
 Backtrack list
 Noted references list
.
.NOTE Paged control keys
 F1 or ?    - This help
 F2 or #    - Page number (*T)
 F3 or PgUp - Previous page
 F4 or Home - Start of list/file
 F5         - Find next (*T)
 F6 or /    - Search file (*T)
 F8 or End  - End of file (*T)
 F9         - Quit (*T Suspend list)
 F10        - Quit (*T Quit list)
 Return     - Select (*T Suspend)
 (*T - Type file control keys)
.
.NOTE Info
   - $9 -
 Frame: $1
 Title: $2
 File : $3
 Date : $4
 Time : $5
 ~ABacktrack ~O2 ~PO2A;NInfo~E with $6 entries
 ~AAutoref ~O4 ~PO4A;NInfo~E
 Error status $? ~C32~AClear~PYah;NInfo~E
.
.NOTE Menu bar
 The menus on the menu bar can be
 selected using their initial
 letters. With a menu on display,
 the options can be selected with
 the initial letter of the option.
.
.NOTE Key mappings
 The following key mappings
 are always provided:-

  q     Quit HyperShell
  n     Next frame
  p     Previous frame
  b     Backtrack one step
  m     Next matching frame
.
.NOTE Key
 A ~Mmenu~PNKey~E gives a menu.
 A ~Nnote~PNKey~E displays a note.
 A ~Freference~PNKey~E allows a
 new frame to be selected.
 An ~Aaction~PNKey~E does some
 other action.
 An ~Iinput field~PNKey~E permits some
 value to be entered.
.
.NOTE Notepad
 The notepad allows you to store a
 reference that you may want to use
 later. The INS key adds the reference
 pointed at to the notepad, or the
 current frame if not pointing at any.
 The DEL key deletes a reference.
 The NOTEPAD option on the main menu
 allows you to select from the notepad
 and delete unwanted references.
.
.NOTE Selecting
 Use the cursor keys or the TAB and
 SHIFT/TAB keys to move to a reference
 Press RETURN to select the reference.
 Press ESCAPE for the control menu, or
 to cancel a menu, note or list.

 When using a mouse, move mouse to
 position cursor to select a reference,
 Press LEFT mouse button to select.
 Press RIGHT mouse button for the
 control menu or to cancel a menu,
 note, or list.

 See Also:- ~NFunction keys~PNFkeys~E
.
.NOTE notation
{param} indicates an
        optional parameter
{param1|param2} indicates
       alternative options
.
.NOTE Fkeys
 F1 Help        F2  Full Contents
 F3 Backtrack   F4  Select back
 F5 Notepad     F6  Search text
 F7 Type file   F8  Do action
 F9 DOS Shell   F10 Quit Program

 See also: ~NKey mappings~E
.
.CHECK +fa
.NOTE Colour configuration
  1.Select colours required ---> Background colour   Foreground colour
  ~DK2.Select scheme to set ─────┐  ~F~T$[~BK Black           ~PV]K~E   ~F~B$]~TK Black           ~PV[K~E
  ~F~DD Default frame title     ~POD$[$]~E~DK   │  ~F~T$[~BB Blue            ~PV]B~E   ~F~B$]~TB Blue            ~PV[B~E
  ~F~DT Frame text / List text  ~POT$[$]~E~DK <─┘  ~F~T$[~BG Green           ~PV]G~E   ~F~B$]~TG Green           ~PV[G~E
  ~F~DR Request / Message line  ~POR$[$]~E~DK      ~F~T$[~BC Cyan            ~PV]C~E   ~F~B$]~TC Cyan            ~PV[C~E
  ~F~DF Frame reference (stack) ~POF$[$]~E~DK      ~F~T$[~BR Red             ~PV]R~E   ~F~B$]~TR Red             ~PV[R~E
  ~F~DE Frame reference (step)  ~POE$[$]~E~DK      ~F~T$[~BM Magenta         ~PV]M~E   ~F~B$]~TM Magenta         ~PV[M~E
  ~F~DA Action reference        ~POA$[$]~E~DK      ~F~T$[~BY Brown           ~PV]Y~E   ~F~B$]~TY Brown           ~PV[Y~E
  ~F~DN Note reference          ~PON$[$]~E~DK      ~F~T$[~BW White           ~PV]W~E   ~F~B$]~TW White           ~PV[W~E
  ~F~DM Menu reference          ~POM$[$]~E~DK    B ~F~T$[~Bk Black blink     ~PV]k~E   ~F~B$]~Tk Grey            ~PV[k~E
  ~F~DS Script reference        ~POS$[$]~E~DK    L ~F~T$[~Bb Blue blink      ~PV]b~E   ~F~B$]~Tb Bright blue     ~PV[b~E
  ~F~DI Input field             ~POI$[$]~E~DK    I ~F~T$[~Bg Green blink     ~PV]g~E   ~F~B$]~Tg Bright green    ~PV[g~E
  ~F~DJ Note heading and border ~POJ$[$]~E~DK    N ~F~T$[~Bc Cyan blink      ~PV]c~E   ~F~B$]~Tc Bright cyan     ~PV[c~E
  ~F~DK Note text               ~POK$[$]~E~DK    K ~F~T$[~Br Red blink       ~PV]r~E   ~F~B$]~Tr Bright red      ~PV[r~E
  ~F~DH Menu heading            ~POH$[$]~E~DK    I ~F~T$[~Bm Magenta blink   ~PV]m~E   ~F~B$]~Tm Bright magenta  ~PV[m~E
  ~F~DC Menu choice             ~POC$[$]~E~DK    N ~F~T$[~By Brown  blink    ~PV]y~E   ~F~B$]~Ty Yellow          ~PV[y~E
  ~F~DO Menu highlighted choice ~POO$[$]~E~DK    G ~F~T$[~Bw White blink     ~PV]w~E   ~F~B$]~Tw Bright white    ~PV[w~E
  ~F~DP Popup messages          ~POP$[$]~E~DK      Example text
  ~F~DU  Scheme U  ~POU$[$]~E~DK ~F~DX  Scheme X  ~POX$[$]~E~DK       ~T$[~B$]*** HyperShell Colour Schemes ***~DK
  ~F~DV  Scheme V  ~POV$[$]~E~DK ~F~DY  Scheme Y  ~POY$[$]~E~DK
  ~F~DW  Scheme W  ~POW$[$]~E~DK ~F~DZ  Scheme Z  ~POZ$[$]~E~DK      [x]  ~A Exit from configuration ~Pq~Kx~E
.
.MENU Colours
Configure   |SColours
Save config |SSave colours
Load config |SLoad colours
.
.SCRIPT Colours
V[K
V]w
LAgain
NColour configuration
JAgain
.
.SCRIPT Save colours
Vf?filename
abq
w$f.hsf
WOA$(&oA)
WOB$(&oB)
WOC$(&oC)
WOD$(&oD)
WOE$(&oE)
WOF$(&oF)
WOG$(&oG)
WOH$(&oH)
WOI$(&oI)
WOJ$(&oJ)
WOK$(&oK)
WOL$(&oL)
WOM$(&oM)
WON$(&oN)
WOO$(&oO)
WOP$(&oP)
WOQ$(&oQ)
WOR$(&oR)
WOS$(&oS)
WOT$(&oT)
WOU$(&oU)
WOV$(&oV)
WOW$(&oW)
WOX$(&oX)
WOY$(&oY)
WOZ$(&oZ)
w
.
.SCRIPT Load Colours
Vf?filename
abq
c$f
.
.SCRIPT Calculator
Ve?Enter expression (x = last result $x)
Vx=$e
pExpr $e = $x
.
.CHECK +fax

.
.SCRIPT perror
p@MError text($?)|Error %s
.
.SCRIPT Picksrch
pPick a word with the mouse
P;Ve&P;abq
A@X$e
.
.SCRIPT SETUP
O#
O16
O*11
-- OUwK
-- OVrk
-- OTWB
KF1MHelp
KM1HELP
KH4SMENBAR
KH3Paged Help
K#nF+
K#pF-
K#bB
K#mF+1
K#qQ
K#iNinfo
K#aNHyperShell
K#lA@C1
Vsfirst
VZ$d?
VrY?Press escape to abort at any time.   (Return to continue)
.
.SCRIPT MENBAR
ZX1;ZY1
.
.PRINT Section 1.
.
.PRINT THIS






             ~F------------ HyperShell Version 5 ------------~E

                           ~DDReference guide~DT

          ~FCopyright (c) Text Technology 1988 - 1993~E
                          ~FAll rights reserved~E















        Text Technology
        66 Kennedy Avenue
        Macclesfield
        Cheshire
        ENGLAND
        SK10 3DE
.
.PRINT PAGE
.
.FRAME HyperShell Reference
.TITLE Section - Introduction
This hyperfile is a reference guide for use by HyperShell authors.
It describes the format of the HyperShell hyperfiles and describes
the specification of references, actions, functions etc. within them
~i0
[1]    ~FFile Contents~K1~E        The structure of the file
[2]    ~FReferences~K2~E        Reference and formatting flags
[3]    ~FActions~K3~E            Command strings
[4]    ~FAction modifiers~PFAction modifier functions~K4~E    Functions returning parameters
[5]    ~FVariables~K5~E        Information storage
[6]    ~FConditions~K6~E        Condition codes
[7]    ~FRestrictions~K7~E        Limits and reserved characters
[8]    ~FCodes~K8~E            Codes and settings
[9]    ~FGeneral~K9~E            Miscellaneous
~i5
.
.PRINT SECTION 2.
.
.PRINT TITLE
Reference Guide - Hyperfile structure
.
.PRINT PAGE
.
.FRAME File contents
.TITLE Section - Hyperfile structure
╔══════════╗ ╔══════════╗                ┌── ╔═════════════════╗
║    H     ║ ║ ~F.INDEX~PFIndex~E   ║ ╔══════════╗   │   ║ ~F.REMARK~PFRemarks~E         ║
║          ║ ║══════════║ ║ ~F.HEADER~PFHeader~E  ║   │   ║ ~F.SCRIPT SETUP~PFSetup Script~E   ║
║    Y     ║ ║  ~FGLOBAL~PFGlobal Items~E  ║ ║ ~F.FOOTER~PFFooter~E  ║   │   ║ ~F.NOTE name~PFNotes~E      ║
║          ║ ║  ITEMS   ║ ╚══════════╝   │   ║ ~F.MENU name~PFMenus~E      ║
║    P     ║ ║ - ~DM OR ~DT - ║ ╔══════════╗ ──┘   ║ ~F.SCRIPT name~PFScripts~E    ║
║          ║ ║          ║ ║ OTHER    ║       ║ ~F.PRINT command~PFPrint~E  ║
║    E     ║ ║ ~F.SHARE~PFShare~E   ║ ║ ITEMS    ║       ║ ~F.CHECK flags~PFCheck~E    ║
║          ║ ╚══════════╝ ╚══════════╝ ───── ╚═════════════════╝
║    R     ║ ╔══════════╗ ─────── ╔════════╗ ╔═════════════════╗
║          ║ ║          ║ ─────┐  ║ FRAME  ║ ║ ~F.FRAME~PFFrames~E ~Fname~PFFrame Name~E     ║
║    F     ║ ║ FRAME    ║      │  ║ SPEC.  ║ ║ ~F.TITLE text~PFTitle~E     ║
║          ║ ║          ║      │  ║        ║ ╠═════════════════╣
║    I     ║ ║ ~FSPECS~PFFrames~E    ║      │  ║        ║ ║ ~F.REMARK~PFRemarks~E         ║
║          ║ ║          ║      │  ║ ~FLOCAL~PFLocal Items~E  ║ ║ ~F.NOTE name~PFNotes~E      ║
║    L     ║ ║          ║      │  ║        ║ ║ ~F.MENU name~PFMenus~E      ║
║          ║ ║          ║      │  ║ ITEMS  ║ ║ ~F.SCRIPT name~PFScripts~E    ║
║    E     ║ ║          ║      │  ║        ║ ║ ~F.PRINT command~PFPrint~E  ║
╚══════════╝ ╚══════════╝      └─ ╚════════╝ ╚═════════════════╝
.
.FRAME Remarks
.TITLE So you know why you did it
 .REMARK
 text lines

A remark section can appear anywhere in the hyperfile, between
other sections. It is followed by lines of text containing
information for the hyperfile author only, and will not be
displayed during a HyperShell session.

Remark sections can be placed before other sections to describe the
function of those sections.

The section, like all sections, is terminated by the next section
identifier (any line starting with '.').
.
.FRAME Check
.TITLE To control the checker component
 .CHECK {-options}{+options}

The Check specification is a single line 'section' signalling the
settings of flags for use by the HyperShell Checker utility (HC).
For details of the parameters, see the chapter on the HyperShell
Checker in the operation guide.

This section is ignored by HyperShell, although it does signify
a new section, and therefore terminates a previous section.
.
.FRAME Print
.TITLE To control the HP printout
 .PRINT command

The Print section is used to control the HyperShell Printer
utility (HP). The following commands are supported by HP.

   .PRINT TITLE    take next line as title string
    (can be used to change the title throughout the hyperfile
   .PRINT PAGE    force new page
   .PRINT SECTION prefix
       define new section prefix and reset frame serial number
   .PRINT THIS     print subsequent lines up to next line
       starting with '.', recognizing format and highlight flags
   .PRINT OFF    disable printing
   .PRINT ON    enable printing
   .PRINT WPOFF print as formatted
   .PRINT WPON  output paragraph as single line, for word processor
   .PRINT LIMIT nn/g    limit print output for encrypted file

This section is ignored by HyperShell, although it does signify
a new section, and therefore terminates a previous section.
.
.FRAME Share
.TITLE sharing globals with another hyperfile
 .SHARE

Indicates that the hyperfile will use the global items from a
master hyperfile (the first hyperfile loaded i.e. the one named
on the command line). All global notes, menus and scripts
(including the SETUP script) are shared, as well as HEADER and
FOOTER sections. Any global items specified within the secondary
hyperfile will only be accessible from that hyperfile, and only
if an item of the same name does not exist in the main hyerpfile.
If an ~FINDEX~E is needed for the hyperfile, this may be specified.
Also .REMARK, .PRINT and .CHECK directives may be used. The
secondary hyperfile can also have local items specified with
the frames.

This is used for splitting large hyperfiles, where a main entry
point can always be used. It is necessary to ensure that any
frame references in global items to frames in the secondary
hyperfile are fully qualified (i.e. they specify the frame
name and hyperfile in the form 'frame^file').
~G
The ~FPreload hyperfile~E action can be used to load the
secondary hyperfiles in the SETUP script of the master file.

The SETUP script will not be performed when moving between
frames in hyperfiles sharing the same globals.

Contents lists will only cover the current hyperfile, but a
search action of the form 'A@s' will present a list of all
frames in all loaded hyperfiles.
.
.FRAME Header
.TITLE Fixed information at the top of the frame
 .HEADER
 (text with ~Freferences~E and ~Fformatting~E)

The header section provides the text that will appear at the top of
the frame display. By convention it contains the name and title of
the frame being displayed, and may also contain date, time,
hyperfile name etc.

The header section is optional. If omitted, a default title is
displayed showing the frame name and title.

A 'null' header consisting of a .HEADER line followed by another
'.' line may be used if each frame is to have a different form, and
does not need the default title.

The header display can be suppressed for certain frames by starting
the frame ~Ftitle~E with a ')' character.
.
.FRAME Footer
.TITLE Fixed information at the bottom
 .FOOTER
 (text with ~Freferences~E and ~Fformatting~E)

The footer section is optional, and provides the text that will
appear at the bottom of the frame display. It is usual to position
it at a fixed line location (Using ~FLine positioning~E) so that
it appears in the same place for each frame. The footer usually
contains references that are present for all frames in the file,
such as a help ~Fnote~PFNotes~E display, a function key
map, a backtrack count display etc.

Alternative and conditional footer texts can be set up using the
conditional hidden line flag (~~hn), and these can be triggered for
each frame using the local setting flag (~~Jn) which sets the
frame local flags e.g.

    .FOOTER
    ~~h8Footer text one
    ~~h8text one continued~~G
    ~~h9~~G
    Default footer text
    more default footer
    yet more default footer
    .

The frame text can then code ~~J8 for footer text one, ~~J9
for no footer and default footer text if no ~~J specified.
If no default required, then only conditional lines are
included. The ~~J8 can be included at the end of the first
text line in the frame, or of course can be set up by actions.

If a footer is specified in this manner, then the maximum
depth MUST be set up in the SETUP script using the ZF
action. For the above, this would be ZF3.

Also the footer display can be suppressed for a frame by
starting the frame ~Ftitle~E with a ')' character.
.
.FRAME Global Items
.TITLE Accessible from all frames
Global items are accessible from any frame in the hyperfile.

Global items are specified at the start of the hyperfile,
before any frame specifications.

~FReferences~E to global items and actions invoking global items
generally start with a capital letter, whereas those to ~Flocal items~E
start with a lowercase letter.
.
.FRAME Local Items
.TITLE Accessible from one frame only
Local items are only accessible from the frame which specifies them.

Local Items are specified after a frame for which they are to be
local. They may only be accessed when that frame is on display,
or when a paged list has been displayed from that frame.

~FReferences~E to local items generally start with a lowercase letter.
If the local item specified in a reference or action does not
exist, a global item with the same name is used, if it exists.
.
.FRAME Setup Script
.TITLE To configure the hyperfile
 .SCRIPT SETUP
 (limited ~Factions~E)

The setup ~Fglobal script~PFScripts~E is acted upon when the hyperfile is loaded,
and when the hyperfile is re-entered after displaying frames from
another hyperfile. It is used to ~Fset key mapping~Es and to set
control options. An initial note display or certain other actions
may also be performed at this stage, but remember that the script
is used on reentry as well as at load time, so may well be executed
many times when the user switches between hyperfiles. It is
imperative not to do a frame display, or any action which would
ultimately cause a frame display.

The setup script is optional.
.
.FRAME Index
.TITLE For large hyperfiles
 .INDEX

The .INDEX line may be present anywhere before the first frame
specification. It signals that an index file is usually present for
the frame. An index file is useful when the hyperfile is above a
certain size, as it saves HyperShell from having to read all the
way through the hyperfile to build its internal index. Opening and
reading the index file has its overheads, however, so its not
always helpful to have the index file in use. An index is generally
of use when a hyperfile has above 30 frames of reasonable size.

The index file is maintained automatically, and is kept in the same
directory as the hyperfile. It has the same name as the hyperfile,
but with an extension of .HIX. If you modify the hyperfile,
HyperShell will detect this and rebuild the index for you. If you
delete the index, a new one will also be built. If the .INDEX line
is not present, HyperShell does not try to use index files.
.
.FRAME Frames
.TITLE The unit of display for HyperShell
Frame specifications are started by a .FRAME keyword. The frame
specification will terminate with the next .FRAME keyword or the
end of the file. There must be at least one frame specification
in a hyperfile. The frame specification includes the frame name
and optional title, along with the text which is to be displayed
for the frame. ~FLocal items~E may follow the frame text.

┌───────────────────────────────────────────────────────────────┐
│   .FRAME ~Fframe name~E~C70│
│   .TITLE ~Ftitle text~PFtitle~E~C70│
│   (~Fframe text~PFtext~E with ~Freferences~E and ~Fformatting~E)~C70│
│   .MENU ~Fmenu name~PFmenus~E        \~C70│
│   (options)                 \~C70│
│   .NOTE ~Fnote name~PFnotes~E          \ Can be a number~C70│
│   (text with references and formatting)      /    of these~C70│
│   .SCRIPT ~Fscript name~PFscripts~E     /~C70│
│   (actions)        /~C70│
│   ~F.END~PFend~E~C70│
└───────────────────────────────────────────────────────────────┘
.
.FRAME Frame Name
.TITLE The key to the frame
 .FRAME frame name

The frame name provides the key to the frame. It is very important
to choose the frame name carefully. The frame name will be used to
cross reference the frame from text in other frames, and it is most
useful if the form of name used in open text is chosen for the frame
name. It is not essential to do this, however, as other words or
phrases can be cross referenced to the frame using ~Fparameter~PFParameter section~Es in
the ~Fframe reference~Es, hidden from display, that refer to the real
frame name.

In general, duplicate frame names should be avoided, as references
cannot then uniquely identify the frame. The first such name is
selected normally, although see ~FFrame selection~E for details of
how duplicate frames can be selected. Also the frame stepping and
backtracking operations can handle duplicate frames. Note that the
HyperShell editor and checker do not support duplicate frame names.

The frame name is limited to 35 characters.
.
.FRAME Title
.TITLE A description of the frame
  .TITLE title text

This line is optional. However, note that the frame title is normally
displayed in the frame display ~Fheader~E. It is also displayed in
any ~Fpaged displays~E containing frame lists, and is used by the
~Fsearch selection~E to locate frames about particular topics.
It is therefore reasonably important, and well worth providing.

The frame title is limited to 40 characters.

If the title for a frame starts with a ')' character, the header
and footer are not displayed for that frame, and the text can use
the bottom line, which is usually kept clear. This may be used for
full screen displays such as those captured from other programs
and translated through the editor components.
.
.FRAME Text
.TITLE The contents of the frame
The frame text comes after the frame name (and title) lines. It
contains the text specific to the frame. This will be displayed
between the ~Fheader~E and ~Ffooter~E sections. The text may
contain embedded ~Freferences~E to other ~Fframes~E, ~Fnotes~E,
~Fmenus~E and other ~Factions~E. Frame references can either be
explicitly marked or may be automatically highlighted using the
~Fautoreference~E facility.

It is recommended that frame text does not take up more than the
number of lines left after the header and footer have been allowed
for. If this does occur, a message is displayed indicating that
further text may be displayed by pressing the PgDn key. Also it is
possible to return to the first screen of a frame by pressing the
Home key. A formatting trigger is provided which will force a
'~Fscreen break~E' after the line in which it occurred. The frame
text is displayed to a width of 80 characters, extra characters
being ignored.
~G
Graphic and other characters from the 256 character set may be
used to draw boxes etc.

A double line box may or an area of different colour may also be
drawn automatically using the area drawing flags ~~a and ~~b.

Automatic indenting of text can be performed by the use of the
~Findent flag~E ~~i.

.
.FRAME Notes
.TITLE Popup windows of text
 .NOTE note name
 (text with ~Freferences~E and ~Fformatting~E)
 .

Notes are small popup windows of text which supply general
information or information additional to the ~Fframe text~PFText~E.
They may contain ~Fformatting~E and ~Freference triggers~PFReferences~E.

The note name can be up to 35 characters.

Notes have a size limit of 22 lines of 76 characters.

~FGlobal~PFGlobal Items~E notes are used for general information in support of
the main material and for help displays.

~FLocal~PFLocal Items~E notes are used for information in support of the frame
to which it is local.

Selections from a note cause the note to be cleared before
continuing.
.
.FRAME Menus
.TITLE Popup selections
 .MENU menu name
 (options)
 .

Menus are popup items which show a list of options for selection.
Each option is supplied on a separate line, and consists of the
choice text, and optionally the associated action for the choice.
For a menu invoked using the ~FM action~PFPopup menu display~E the options are treated as
frame names, if the action string is not supplied. An action
string is separated from the choice text by the '|' character.
If action type indicator symbols (see ~FOptions~E) are to be used, it
is good practice to line up the action separator, so that the
symbols line up on the right of the menu display.

The menu name should not exceed 20 characters. There is no limit
to how many items can appear in a menu, but only 20 options are
displayed at a time, scrolling being performed by the selection
of the scrolling option on the top and/or bottom.

For multi-page menus, the up/down arrows will switch to the prev or
next page of menu when they reach the corresponding end of the menu
display. The PgUp and PgDn keys may be used to move up and down
through the menu pages.
~G
~X1Example:

The following menu has the actions described afterwards:-

   .MENU various
   starting
   help        |Nhelp
   next frame  |F+
   exit program|Q
    .

The first option, when selected, displays the frame 'starting' in
the current hyperfile.

The second option displays a global popup note called 'help'.

The third option moves to the next frame.

The fourth option quits the HyperShell program.
~G
A menu may also be used as a lookup table, and referenced via the
lookup modifier (e.g. Mmenuname[key]). In this case it is necessary
to place the action separator directly after the option text, and
to always supply the action string. If a menu is to be used with a
direct index specifier (e.g. Mmenuname(3)), the action string is
not normally required.

Menus can have options which are conditional. These are indicated
by lines starting with a '?' or a '\' character, followed by a
single character ~Fcondition code~PFconditions~E. For the '?' variant,
the menu option is included in the menu if the condition is TRUE,
otherwise it is excluded. For the '\' variant, the line is only
included if the condition is FALSE. Thus the following menu displays
different options depending on the setting of the error status.

   .MENU errors
   ?sClear error status  |Y
   ?sShow error status   |P$?
   \sRun program         |D123
   .
.
.FRAME Scripts
.TITLE Sequences of actions
 .SCRIPT script name
 (limited ~Factions~E)
 .

Scripts are sequences of actions, used where a simple action string
or a multiple action string are not sufficient. A script can be used
to display a sequence of notes, to input a number of variables to
construct a command line, or for many other more complex purposes.

Scripts are limited to 200 lines, and each line may contain a
number of actions up to a maximum length of 128 characters.

A script is terminated when:-

    1.    It reaches the end, or a 'q' action
    2.    A further script is called
    3.    ESC is pressed to cancel a menu or other display
    4.    A new frame is displayed (unless using 'f' action)
~G
A number of control actions exist to allow looping and conditional
branching, and ~Fexpression evaluation~E permits simple integer
arithmetic to be performed on ~Fvariables~E. The ~FJump within script~E
and ~FLabel in script~E actions may be used to perform control flow.
~FSubroutines~PFCall subroutine~E can exist within scripts to perform common
sequences of actions.

Lines starting with a '-' sign are treated as comment lines,
and are not loaded with the script. Also completely blank lines
are ignored. It is helpful to have comments to explain how the
script works, for when you need to change the script.

Lines in the script can be indented with spaces or tabs, and
these are ignored when the script is loaded. Indentation can
show the structure of a script.

A script can contain a line of the form

    +scriptname

in which case script 'scriptname' is appended to the script.
Only one script can be appended, although that can itself append
another script. The total number of lines is limited to 200.
Subroutines can then exist in a separate script which can be
appended to script wishing to use them. If this is done, the first
line of the script can be a 'q' action, in case the first script
runs off the end by accident. A local script of the given name is
firstly looked for, and then a global script, if a local script
is not found.

Scripts cannot be 'nested'. When a script calls another script
the original script is cleared first, effectively 'chaining'
from one to another.

Also see ~FScript control structures~E for details of how control
loops can be coded in scripts.

An ~Fexample script~E is provided to show how the control flow
actions can be used.

Also see ~FLabel in script~E for details of how problems
with scripts can be dealt with.
.
.FRAME Script control structures
.TITLE Block structures using { and }

These block control structures have been introduced to facilitate the
production of complex scripts, and to improve the maintainability and
readability of scripts.  The control structures may only be used in
scripts. Any kind of script may utilise these, including the SETUP
script.  Indentation of levels may be used to help readability.

The '{' and '}' characters are used to indicate the start and end of
control flow structures. They must appear as the first non-blank
character on a line. They are explained below.

They must not have anything else after them on the line, and cannot
have multiple actions on the same line.

Some of these count as two lines (out of the maximum of 200 for a
script), so care must be taken when writing large scripts.

Blocks may be nested. eg. an if block may have a loop within it.  The
maximum nesting depth is 10.

If/Else block

      {ic
       - if c true -
      }

         and, for 'if not'

      {nc
       - if c false -
      }

         or the extended form, for 'if / else'

      {ic
       - if c true -
      }e{
       - if c false -
      }

         and, for 'if not / else'

      {nc
       - if c false -
      }e{
       - if c true -
      }

While and Until loops

1. Start condition

Actions are not performed if condition not met

      {wc
       - while c true -
      }

      {uc
       - until c true -
      }

2. End condition

Actions are performed at least once in all cases

      {
       - while c true -
      }wc

      {
       - until c true -
      }uc

It is possible to have both a start and end condition on the same
loop. eg:-

      {wc
       - while c true -
       - until d true -
      }ud

General loop

      {
       - actions -
      }

or

      {
       - actions -
      }xc{
       - actions -
      }

- The }xc{ will exit the loop at that point if condition c is true.
  The condition # may be used for unconditional exits.

- More than one }xc{ may appear in the loop.

- A }xc{ may also appear in a while or until loop.

- A }e{ or }xc{ must appear at the correct level. ie. it must
  not appear in an inner loop or inner if structure.

- A }e{ in a loop structure, or a }xc{ in an if structure will be
  treated as the end of that structure (ie. as a } without arguments).

Example 1. File processing

      -- open file
      rdata.txt
      {
        -- read record from file
        Rabcd
        -- exit loop if end of file
      }xz{
        -- if an order record, process it
        vaorder
        {ie
          oItem $b, quantity $c, price $d
          Vt=c*d
          oTotal price $t
        -- else report record type
        }e{
          pRecord type $a not processed
        }
      }
      -- close file
      r

Example 2. Data entry

      -- open file
      wnames.dat
      {
         Vx?name
         -- if not blank, write to output
         {nb
            wName added = $x
         }
      -- loop until blank input
      }ub
      -- close file
      w

.FRAME End
.TITLE The end of the frame specification
The .END keyword indicates the end of the frame specification.

It is present for historical reasons, and serves no purpose
other than to indicate to the author where a frame finishes.
This may therefore be omitted, as the next frame specification
serves the same purpose.
.
.PRINT SECTION 3.
.
.PRINT TITLE
Reference Guide - References
.
.PRINT PAGE
.
.FRAME References
.TITLE Section - link references and control flags
In the frame text, in the text of a popup note and in the text of
a file displayed using the 'Type file' action, control sequences
can exist to indicate references to other items, which are
highlighted in the text, and to perform text formatting actions.

Reference control sequences have the general form:-

   ~~?text string~~E   OR   ~~?text string~~Paction string~~E

Where ? is the reference type identifier, and text string is the
text to be displayed, highlighted in a manner applicable to its
type, in the frame text display. action string is an optional
action string which will be performed instead of the implicit
action for the reference if the reference is selected.

The text string and action string elements are limited to 39
characters (although a longer text string may be used where
an action string is supplied).
.
.FRAME Frame reference
.TITLE Flags ~~F and ~~f
~~Fframe name~~E
~~Freference~~PFframe name~~E

The frame reference is introduced by the ~~F or ~~f sequence. The
~~F reference adds the reference to the backtrack list, when
selected. The ~~f reference replaces the top entry on the backtrack
list. Thus ~~F is used for browsing or cross references, and ~~f is
used for deliberate frame sequencing or hierarchical references.
The ~~f type of reference is highlighted in a different manner to
tell the user that selection of the reference will not allow
backtracking. A ~Fparameter section~E (~~P) may be added to supply an
explicit action string to be performed on selection.

    ~~Fdeleting~~PFDelete~~E     - reference to frame 'Delete'
.
.FRAME Note reference
.TITLE Flags ~~N and ~~n
~~Nnote name~~E
~~Nreference~~PNnote name~~E

The note reference is introduced by the ~~N or ~~n sequence. The
~~N reference is a global note, whose specification occurs at the
start of the hyperfile, before the first frame specification. The
~~n reference is a local note, whose specification lies within the
current frame specification, after the frame text and before the
next frame. A parameter section (~~P) may be added to supply an
explicit action string to be performed on selection.

   ~~NHelp~~E       - reference to global note 'Help'
.
.FRAME File note reference
.TITLE Flag ~~t
~~tfile name~~E
~~treference~~Ptfile name~~E

The file note reference is introduced by the ~~t sequence. This
causes a file with a name equal to the reference (and with default
extension '.NTE') to be displayed as a popup note. See the 't'
action for further details. A parameter section (~~P) may be added
to supply an explicit action string to be performed on selection.

    ~~tmemo~~E     - reference to file MEMO.NTE
.
.FRAME Menu reference
.TITLE Flags ~~M and ~~m
~~Mmenu name~~E
~~Mreference~~PMmenu name~~E

The menu reference is introduced by the ~~M or ~~m sequence. The
~~M reference is a global menu, whose specification occurs at the
start of the hyperfile, before the first frame specification. The
~~m reference is a local menu, whose specification lies within the
current frame specification, after the frame text and before the
next frame. A parameter section (~~P) may be added to supply an
explicit action string to be performed on selection.

   ~~msizes~~E      - reference to local note 'sizes'
.
.FRAME Script reference
.TITLE Flags ~~S and ~~s
~~Sscript name~~E
~~Sreference~~PSscript name~~E

The script reference is introduced by the ~~S or ~~s sequence. The
~~S reference is a global script, whose specification occurs at the
start of the hyperfile, before the first frame specification. The
~~s reference is a local script, whose specification lies within
the current frame specification, after the frame text and before
the next frame. A parameter section (~~P) may be added to supply an
explicit action string to be performed on selection.

     ~~Scalculate~~E      - reference to global script 'calculate'
.
.FRAME Action reference
.TITLE Flag ~~A
~~Areference~~Paction string~~E

The action reference is introduced by the ~~A sequence. This form
of reference contains an action which is not a frame, note, menu or
script reference. It covers the miscellaneous actions whose
multiplicity precludes the use of specific highlighting schemes.
The action reference usually contains the parameter section (~~P
sequence), as it has no implicit action. If the reference text
can be used as an action, then the parameter may be omitted.

    ~~Agreen~~PPindicates safety~~E   - reference to popup message
.
.FRAME Input field
.TITLE Flag ~~I
~~Iinput area~~Paction pattern~~E

The input field is not exactly a reference, but is used to input
data to be used by the application. Its most general use is to
input variable values. The input field always has reference text
and a parameter section, which specifies a pattern within which
the input value is substituted prior to execution.

The reference text part of the input field delimits the field, and
provides the text which is to be edited to form the input to the
field. If the input field is being used to set a variable, the
reference text usually contains an expansion token for the variable,
so that when the frame is displayed, the current value is displayed
in the field and can be edited. The field should contain a width
specification after any reference text, which will determine the
width of the input field. If new input is always required, the
field should be blank, just a width being supplied in the reference
text.
~G
The parameter section usually consists of a variable assignment and
sometimes some other action. The parameter string provides a
pattern, within which the input value is substituted. The string
can contain up to three occurences of the string '%s', each of
which will be replaced by the value when it is input.

An example of a line containing an input field is as follows:-

   Name : ~~I$$n~~W15~~PVn%s;scheckname~~E

This, when selected, allows the current value of variable 'n'
to be edited (up to 15 characters in length), which is the assigned
back to variable 'n' and checked using local script 'checkname'.
When displayed, this will look like (assuming variable n contains
'Fred Jones'):-

   Name : ~DIFred Jones     ~DT

The input field may also be specified in a note, although the note
display will terminate after entry of the input field.
.
.FRAME Parameter section
.TITLE Flag ~~P
The parameter section, introduced by the ~~P sequence, permits any
action to be associated with a reference. It is usual, and helpful,
to use the same type of action as that suggested by the initial
introductory sequence, as it is that which has already determined
the highlighting scheme for the reference. If a miscellaneous
action for which there is no set colour scheme is to be performed,
the ~Faction reference~E should be used.

See also ~FActions selected from note~E
         ~FSingle line help string~E
.
.FRAME Actions selected from note
.TITLE Special flag !
If an action string in a reference in the note text has a '!' at the
start, the action string is executed immediately the reference is
selected, without popping down the note. The '!' is removed before the
action is performed.

IMPORTANT NOTE:- DO NOT use actions resulting in other popup items,
message line outputs or inputs, or movement to another frame,
otherwise results will be unpredictable.

This is useful for multiple input fields, and for other dialogue box
features.

Positioning using the ~~X and ~~Y are relative to the top left, so if
actual position is to be used, window should be reset to the full
screen using Zr first.

eg.

      .NOTE dialogue
      This handles a set of toggles
      toggle local flag 1 ~~A.~~P!Stoggle(1)~~K1~~E
      toggle local flag 2 ~~A.~~P!Stoggle(2)~~K2~~E
      toggle local flag 3 ~~A.~~P!Stoggle(3)~~K3~~E
      .SCRIPT toggle
      -- first toggle flag
      ZL$$\#
      -- then set display flag accordingly
      a$$\VS*
      z$$\VS.
      -- reset for display
      Zr
      -- get x and y coords
      VX&w1;VY&w2
      -- display . or *
      i~X$$X~Y$$Y$$S
      .
.FRAME Single line help string
.TITLE Use of + in action string

A facility is provided to allow single line help strings to appear
for references over which the mouse is positioned. This facility is
triggered by the action string for the reference starting with a
psuedo-action of the form:-

     +x

If the mouse cursor is positioned over such a reference, the action
mapped to the single quote character will be performed (' = ASCII
39).  When the cursor is moved away from such a reference, the
action mapped to the single backquote character is performed (` =
ASCII 96).  The action should be set up in the SETUP script to
perform a 'p' action. For example:-

    K#'p@Mhelpline[$$$$(&Q2)]

This example uses a menu (which can be either a global or a local
menu) as a lookup table, to supply the text for the help line. Note
that the &Q function is used to extract the first two characters of
the reference string for use as a key for this purpose (The
parameter to the &Q function has been added in support of this for
HyperShell V5).

The action for the off-reference mapping should simply clear the
message line as follows:-

      K#`p

The menu should then be defined in the following manner:-

    .MENU helpline
    +1|Help notes
    +2|Contents list
    +3|Backtrack to last frame
    +4|Main menu
    +5|Print frame
    +6|Search for text
    +7|Type a file
    +8|Perform HyperShell action
    +9|DOS shell
    *|No help available
    .

The '*' acts as a default in case a string has not been supplied
for a particular reference.

So, if a reference is defined as follows:-

    ~~MHelp~~P+1;MHelp~~E

and the cursor is positioned over the reference, the help message
'Help notes' is displayed on the message line.

It is also possible to define named variables which contain the
help message strings. An example of this is given in the graphic
hypershell demo hyperfile.
.FRAME Key mapping
.TITLE Flag ~~K
The key mapping sequence, introduced by ~~K, permits a key on the
keyboard to be mapped to the reference, such that when it is
pressed, the reference is selected. This is useful for 'menu'
frames. A key mapped using the 'K' action takes precedence over
this form of key mapping. The reference:-

   ~~FNext frame~~Pf+~~K ~~E

will have 'Next frame' highlighted as a frame reference, and will
move to the next frame when selected directly or when the space bar
is depressed.
.
.FRAME Immediate reference
.TITLE Flag ~~Q
One reference on a frame or note display may be flagged as an
'immediate' reference, which will be selected automatically after
the frame or note text has been displayed. This is done by including
the sequence ~~Q after the complete reference sequence for the
reference to be selected. This may be used for many purposes, but the
most common would be to select the first input field on a form frame,
and therefore put the frame into a data input mode automatically on
entry.

The immediate reference flag may also be used with an 'invisible'
reference. This has a zero length reference string and does not
therefore permit manual selection. This could be placed in the header
or footer to, for instance, write a log file of frames visited. It can
also be used to pop up a note or a menu on moving to a frame. It may
even invoke a script which could perform a long sequence of actions.

    ~~A~~PNhello~~E~~Q
.
.FRAME Formatting
.TITLE Format control flags
The formatting sequences permit the frame, and note, displays to be
controlled in a number of ways. Absolute cursor positioning and
colour control are the main uses for this feature.

Formatting sequences can be placed within the reference text,
provided that a parameter section is provided for that reference.
This facility can be used to highlight a letter in the reference,
if that letter key is mapped to the reference.
.
.FRAME Option display
.TITLE Flag ~~O
The option display is an extended form of variable display. It
allows the state of various runtime options to be displayed as
either 'ON' or 'OFF'. The runtime options are as follows, showing
the option code, the command line flag and the option description
with the default state which is toggled by the flag.

   ~~O2           displays ON or OFF depending on backtrack status

It is possible to access options in the extended option set using
the following characters:-

O*0':' O*1';' O*2'<' O*3'=' O*4'>' O*5'?' O*6'@' O*7'A' O*8'B' O*9'C'

The special form ~~O# displays a three character field containing
current page number of a multi screen frame. This can be used with
~Flocal flag~PFlocal flags~E '<' to show a conditional footer with the page number.
.
.FRAME Line positioning
.TITLE Flag ~~L
~~Lnn

The line positioning command, introduced by the ~~L sequence,
positions the text writing cursor at the default indent of the
specified line, unless that line is before or at the current line,
or beyond the bottom of the display or footer margin. The full
form of the sequence is either ~~Ln or ~~Lnn, where n/nn is the
line number, starting from 1. Thus:-

   ~~L3          positions at line 3, column 1

   ~~L20         positions at line 20, column 1
.
.FRAME Column positioning
.TITLE Flag ~~C
~~Cnn

The column positioning command, introduced by the ~~C sequence,
positions the text writing cursor at the specified column, by
outputting spaces, unless that column is before or at the current
position, or beyond the edge of the display. The full form of the
sequence is either ~~Cn or ~~Cnn, where n/nn is the column number,
starting from 1. Thus:-

   ~~C9           positions at column 9

   ~~C74          positions at column 74
.
.FRAME Width positioning
.TITLE Flag ~~W
~~Wnn

The ~~W sequence, of the form ~~Wn or ~~Wnn, outputs spaces to
the display upto the specified number of column positions from
the start of the last reference, or the start of the line if no
references yet displayed.

This is normally used to specify the width of an ~Finput field~E.
It may, however, be used for other purposes.

    ~~W12         positions 12 columns from start of reference
.
.FRAME Force column position
.TITLE Flag ~~X
~~Xnn

The force column position flag, introduced by the ~~X sequence,
positions the text writing cursor at the specified column of the
current line, regardless of the current position. The full form
of the sequence is either ~~Xn or ~~Xnn, where n/nn is the column
number, starting from 1. Thus ~~X34 positions at column 34.
This flag is usually used in the ~FInsert text~E action.

The position set by the ~~X flag can be used to start a width
range, so that the ~~W flag may be used to clear part of a line.

CAUTION: this flag should be used with care
.
.FRAME Force line position
.TITLE Flag ~~Y
~~Ynn

The force line position flag, introduced by the ~~Y sequence,
positions the text writing cursor at the current column of the
specified line, regardless of the current line position. The full
form of the sequence is either ~~Yn or ~~Ynn, where n/nn is the
line number, starting from 1. Thus ~~Y10 positions at line 10.
This flag is usually used in the ~FInsert text~E action.

CAUTION: this flag should be used with care
.
.FRAME Screen break
.TITLE Flag ~~G
In the frame text, a 'new page' (or second screen) of text may be
forced after the current line by the inclusion of the screen break
trigger. The form of this sequence is ~~G, and this may occur at
any point in the line, although it is probably easiest to maintain
if placed at the end of the line.

      . . . . line at end of screen 1 ~~G
    Line at start of screen 2 . . . .
.
.FRAME Line break
.TITLE Flag ~~g
In frame or note text, a new line can be started by embedding this
flag in the text.

This is used where ~Fnamed variables~E hold text to be displayed
which occupies more than one line.

    This line~~gNext line
.
.FRAME Concatenate text
.TITLE Flag ~~c
~~c

The ~~c flag may be placed at the end of a line, if the next line
is to be concatenated. This flag has special applications and should
not be used in open frame or note text. It is usually used with the
'i' action to retain the text position after writing to the screen.

CAUTION: This flag should be used with care
.
.FRAME Hidden lines
.TITLE Flag ~~H
~~Hc

Lines in the text can be excluded from a frame or other display by
putting a ~~H sequence at the start of the line. If the ~~H flag
appears after the first column, it marks the start of a hidden area
which finishes at the end of the line or at a ~~Z flag. The ~~H flag
can be used for embedding maintenance comments in frame text, which
will not be displayed.

~X1See also: ~FConditional hidden lines~E
.
.FRAME Conditional hidden lines
.TITLE Flags ~~h and ~~j
~~hc       - display text if condition c is TRUE
~~jc       - display text if condition c is FALSE

These sequences provide a conditional hidden text capability.
The 'c' character is one of the general HyperShell ~Fconditions~E.
When the condition is FALSE, the ~~hc sequence acts as ~~H to hide a
complete line or part of a line terminated by ~~Z. When the condition
is TRUE, the sequence has no effect, permitting the text to be
displayed. The ~~jc sequence has the opposite effect, whereby if the
condition is TRUE the text is hidden, else it is displayed.

The conditional hidden text flags are generally used for information
which is ~Fexpanded 'in line'~PFlocal flag toggle~E with the main text. The frame
~Flocal flags~E 0 to 9 are usually used for this purpose.

~X1See also: ~FHidden lines~E
.
.FRAME Print suppress lines
.TITLE Flag ~~p
~~p

Lines in the text which are only required for online display can be
excluded from printout when using the HP program by putting a ~~p
sequence at the start of the line. If the ~~p flag appears after the
first column, the rest of the line is not printed.
.
.FRAME Flag setting
.TITLE Flag ~~J
~~Jn

The local flags 0 to 9 can be set using the ~~J flag. The sequence
sets the local flag 'n' IMMEDIATELY it is encountered. This is
used for setting the local flags to influence the frame display
or operation in some way, mainly for conditional text in the
footer section of the display, where the conditional hidden line
flag is used.

   ~~J3            - sets frame local flag 3

~X1See Also:     ~FHidden lines~E
.
.FRAME End of hidden range
.TITLE Flag ~~Z
The ~~Z flag is used to terminate the range of a hidden or
conditionally hidden piece of text in a frame or note.

    start of line ~~h2Hidden text~~Z

~X1See Also:     ~FHidden lines~E
.
.FRAME Text/Background colours
.TITLE Flags ~~T and ~~B
~~Tc
~~Bc

These sequences set the text colour or background colour to the
colour with code 'c'. The text can have one of 16 different
'colours' and the background can have one of 8. It is helpful to
choose these so that they have a good contrast. And yes, if you
make them both the same, the text is invisible.

   ~~Tr             - set text bright red
   ~~BM             - set background magenta

~X1See also:     ~FColour codes~E
.
.FRAME Display colour schemes
.TITLE Flag ~~D
~~Ds

The ~~D sequence selects colour highlighting scheme 's'. There are
26 colour schemes, mapped to the letters A to Z. The scheme letter
is specified directly after the ~~D. The colour scheme sequence
works slightly differently to the text/background settings in that
it is held over a reference display.

The schemes are configurable using the option setting action 'O'.

     ~~DM             - use menu reference colour scheme

~X1See also:     ~FColour schemes~E
.
.FRAME Indent flag
.TITLE Flag ~~i
~~in

The indent flag can be used to cause an indent to be added
automatically to the text in a frame display. The parameter 'n'
is a digit from 0 to 9 indicating the indent to be applied.
A value of 0 causes no indent.

    ~~i5             - indent the text by 5 places

The flag is usually placed at the end of the header to cause the
frame body text to be indented, and possibly at the start of the
footer to reset the indent before the footer.

Indivual lines can be reset to column 1 by prefixing them with
the sequence '~~X1'. Ranges of lines can have the indent changed
before the start and after the end.
.
.FRAME Box start
.TITLE Flag ~~a
~~a

This flag indicates the TOP LEFT position of a graphic box.

~X1See also: ~FBox draw~E
.
.FRAME Box draw
.TITLE Flag ~~b
~~bt

This flag indicates the BOTTOM RIGHT of a box area, and causes
the area to be drawn from the top left position indicated by a
~FBox start~E flag. The 't' parameter indicates the type of
area, as follows:-

    ~~b0    -- just return to position of ~~a flag
    ~~b1    -- draw a double edged box
    ~~b2    -- define a window and clear it
    ~~b3    -- draw a box, then define a window within it
    ~~b4    -- define window as full screen    (used by itself)
    ~~b6    -- clear the area without defining a window
    ~~b7    -- draw box and clear inside without defining window

Most of these specify window areas and are for use with the 'i' action.
Only the ~~b1 version should be used in frame displays generally.

CAUTION: This flag should be used with care
~G
Example boxes

  ~~a                ~a
      This is in a box        --     This is in a box
                        ~~b1                ~b1

  ~~a                ~a

               ~~DJ~~b3                        ~DJ~b3
~a Text in a box window~b4
~Y18

~DTThis feature can also be used for 'subwindows' or panelled windows,
along with the ~FTake copy of screen~E and ~FShow saved screen~E actions.

~X1See also: ~FBox start~E
.
.FRAME Wait in display
.TITLE Flag ~~w
~~ws

The ~~w flag causes a delay of 's' seconds before proceeding with
the display. This is used for effect.

    1~w12~w13

~X1See also: ~FTeletype mode~E
.
.FRAME Teletype mode
.TITLE Flag ~~d
~~d

The ~~d flag causes text to be slowly displayed as though by
an old fashioned teletype. The flag acts as a toggle, and is
valid for the current line only.

It is used for special effects, and is useful to focus attention
on the text.

  Type this ~dslowly at first~d and then fast

~X1See also: ~FWait in display~E
.
.FRAME Flag character display
.TITLE To actually display a ~~
The ~~ character can be displayed in a frame, note or paged list
by coding it as two ~~ signs:-

~~~~
.
.FRAME Graphic reference
.TITLE Flag ~~R [G]
Within frame or note text, the following constructs are used. The first
is used to execute a sublanguage command immediately. The second does
the same, but is also used to define a selectable graphic reference.

~~Rcommands^item~~E          execute sublanguage 'commands^item'

~~Rcommands^item~~Paction~~E  same as above, also define a reference

Example: Show graphic of mouse and display note if selected

    ~~RLTP^MOUSE.HGP~~PNAbout mice~~E

Show graphic of car, but do not define a selectable reference:-

    ~~RLTP^CAR.HGP~~E

Note that the 'ZZ' prefix MUST NOT be added to the sublanguage commands
string when it is used in frame or note text in this fashion, otherwise
it will be interpreted as two wait commands.

The ~~R and ~~E sequences work differently to the text reference
equivalents. For the immediate display option, the ~~E will only suppress
the creation of a reference if a ~~P, ~~K or other flag is not encountered
after the sublanguage statement.
.FRAME Terminate sublanguage command
.TITLE Flag ~~z [G]
The ~~z flag may be used in certain kinds of graphic references
to terminate an image name and start an action mapping. Eg.

    ~~N~~PLTP^NOTE.HGP~~zNA note~~E

It is preferable to use the ~~R format in most cases.

See also: ~FGraphic reference~E
.FRAME Terminate image for display only
.TITLE Flag ~~e [G]

A ~~e sequence may be used in place of the ~~E where the graphic
display should not be treated as a reference, even if an introductory
flag other than ~~R is used or a ~~P sequence has been coded.

.FRAME Depth of reference
.TITLE Flag ~~y [G]

The graphic image selection is implemented by adding a 'depth' to
the reference, which is loaded with the depth of the displayed image.
The depth can be added to a normal text reference by coding the
sequence ~~ynn where nn is the depth in character cells (default
is 1 for normal references). This may also be used after the ~~P
of a graphic reference to adjust the selectable depth of the image.
.FRAME Select font
.TITLE Flag ~~v [G]
Format:   ~~vx

The ~~v flag introduces a font change:-

   ~~vX   where X is A to Z to represent banks 1 to 26
         A value for X of @ represents the base bank

   The bank is added to the base font number eg.

   ~~vA   sets font 1 as follows:-
         chr001.udg if base is chr000.udg
         chr101.udg if base is chr100.udg
         chr201.udg if base is chr200.udg

    eg. this is base font ~~vBthis is font 2~~v@ this is base font

This permits the font selection to be independant of the adaptor.
.FRAME Do bitmap command
.TITLE Flag ~~U [G]
Format:   ~~Ux

This flag is for embedding font loads etc. into text:-

~~Ux    - Pass contents of variable GUx to sublanguage processor

eg.   ZVGUR=DF^ROMAN.UDG       - set up variable to load font
                                 from compressed variable
              ~~UR              - trigger new font

This can also be used instead of ~~Rxxxxx~~E to do graphic block
displays etc.
.FRAME Do draw command
.TITLE Flag ~~u [G]
Format:   ~~ux

This flag processes the contents of variable Gux through the
drawing sublanguage, immediately it is encountered in the text.
This is used to permit common sequences to be coded in one place
and invoked as required. The character 'x' can be any alphabetic
or numeric character, or certain other characters, provided they
do not conflict with the variable definition or the display
interpretation.

eg. store commands to draw a white line 47 pixels long, to the right

    ZVGu3=L647w

Invoke commands stored in variable Gu3

    ~~u3
.PRINT SECTION 4.
.
.PRINT TITLE Flag ~~
Reference Guide - Actions
.
.PRINT PAGE
.
.FRAME Actions
.TITLE Section - HyperShell control commands
Actions are the commands which control HyperShell.
Action specifications, including ~Fmultiple actions~E can be
supplied at a number of different places:-

   1. The reference action in the text.
   2. A menu action.
   3. A script action.

Not all forms of action specification are relevant in all places.
It is normally obvious where a particular type of action modifier
string is not applicable, or where a particular action is not
sensible. In particular, control flow actions are only relevant in
scripts (although a popup note or menu may cause a branch within a
currently executing script).
.
.FRAME Multiple actions
.TITLE A string of actions
Multiple action strings can exist in any action specification.
The actions are separated by ';' characters. Multiple actions
are permitted wherever an action specification is expected.

  ZX40;ZY12 - Positions the cursor in the middle of the screen.

The following rules apply to multiple action strings:-

1. The condition of a ~Fconditional action~E affects remaining
   actions.
2. A conditional ~Fjump within script~E does not clear remaining
   actions.
3. The remaining actions are cleared if an error occurs in an
   action, or an input is cancelled.
4. If a further multiple action is encountered, for instance as
   the result of an action modifier or menu selection, the
   remaining actions are cleared in the original.
.
.FRAME Action codes
.TITLE Command letters
Action specifications start with a single letter action code, or
a double letter ~Fextended action code~PFExtended action codes~E (starting with Z).

An action may also have parameters supplied directly after the
code. The parameters may be supplied directly as literal strings
or indirectly via one of a number of ~Faction modifiers~PFAction Modifier functions~E.
.
.FRAME Perform action
.TITLE Action 'A'
~X1Format:   Aactionspec

The 'A' action is provided to enable action modifiers returning full
action specifications to be serviced. For example the extended
directory listing modifier 'l' and the notepad listing modifier 'R'
both return action strings, and would be handled as follows:-

   A@l*.*

   A@R

Also the form 'A?Enter action' can be used to permit the user to
enter an action specification for execution.
.
.FRAME Conditional action
.TITLE Action 'a'
~X1Format:   acxxxxxxx{;actionstring}{;actionstring}...

The 'a' action is used to execute an action or set of actions
conditionally on the setting of the condition 'c' specified.

This action provides a means of specifying conditional actions
without having to use scripts.

The condition letters are described in the ~Fconditions~E section.

  adpvariable not defined   - displays message if variable not set

~X1See also:       ~FUnless condition~E
.
.FRAME Backtrack one step
.TITLE Action 'B'
~X1Format:   B

HyperShell retains a list of frames that the user has displayed.
This list acts like a 'stack' which has a frame reference 'pushed'
when a new frame is displayed. The 'B' action 'pops' the frame
references from this stack one at a time, displaying the frame
referenced.

~X1See also:       ~FMultiple backtrack~E
.
.FRAME Multiple backtrack
.TITLE Action 'b'
~X1Format:   b{depth}

The 'b' action permits a number of frames to be discarded from
the backtrack list, retaining the depth specified as a numeric
parameter, where 0 represent the first frame visited in the file.
After this it displays the frame referenced at that point. This
action is usually used with the 'B' dynamic menu, to permit the
point in the list to be selected. If a frame from the backtrack
is to be revisited without winding back, the 'b' dynamic menu
should be used with the A action.

   b@B             Select level and unwind

   b3              Unwind to level of 3

~X1See also:    ~FSelect backtrack~E
.
.FRAME Change drive / directory
.TITLE Action 'C'
~X1Format:   C{Wd:}{pathname}

The 'C' action allows the working directory to be changed, and
optionally allows the working drive to be altered. For example:-

   CB:\HYPER

   CSUBDIR

   C..\HYPER2

The original drive:directory is held in system variable 8, and the
current drive:directory is held in system variable 7. Thus the
action 'P$$7' would display the current working drive:directory,
and the action 'C$$8' changes back to the original directory.
.
.FRAME Call script file
.TITLE Action 'c'
~X1Format:   cscriptfile

The 'c' action permits a file containing a script to be executed.
The 'scriptfile' parameter may have its extension omitted, in which
case .HSF is assumed. Script files are treated as normal ~Fscripts~E,
and obey the same rules. A file script cannot be appended to a
script, but can append normal scripts itself.

Script files can be used as small 'programs'.

~FParameters~E can be supplied on a script action.

   creload             - runs the script file RELOAD.HSF

~X1See also        ~FExecute script~E
.
.FRAME DOS command execution
.TITLE Action 'D' and 'd'
~X1Format:   D{ }{Command line}
     d{ }{Command line}

This action starts the DOS command processor to run a command or to
permit command line interaction. If a parameter is supplied, it is
issued as a command line to DOS. The command can be a DOS built-in
command, a batch file, or an external program. The command can have
parameters.

If the action is specified without parameters, it runs the command
line interpreter to allow the user to interact with DOS. When the
user has finished, the EXIT command is used to return to
HyperShell.

The uppercase form of the action indicates that when the command
has finished, a key press is required before redisplaying the
current HyperShell frame again. The lowercase form indicates that
when the command has finished, HyperShell will immediately
redisplay the current frame. The system variable '^' is set to the
exit code of the DOS command processor (this is always 0!).

If the command line contains a space character as the first
character, the screen is not cleared before invocation or refreshed
afterwards, allowing 'silent' commands, or commands with redirected
output to be executed without disturbing the display. If the command
does output to the screen, the display will be disturbed, but can be
refreshed using the 'y' action. It is preferable to ensure that the
command will never output to the screen. ~FOption~PFOptions~E O6 can be set so
that the HyperShell program is saved to disk whilst a command runs
(this is only possible with the HS.EXE program). Examples:-

   D        - escape to command line allowing return

   DDIR/W *.HYP    - Do wide directory listing of hyperfiles

   d DEL DATA.DAT    - Silently delete a file

~X1See also:       ~FExecute program~E
.
.FRAME Command chaining
.TITLE Action 'E'
~X1Format:   ECommand line

The 'E' action executes another program, overwriting HyperShell in
memory. Only programs (files with .EXE or .COM as an extension)
can be executed using this action. If subsequent return to
HyperShell is required, either the 'D' action or the 'X' action
should be used, although these will mean that the program has less
room in which to execute, as HyperShell occupies around 120k of
memory.

   Edbase                - chains the dbase program

~X1See also:       ~FDOS command execution~E, ~FExecute program~E
.
.FRAME Expand, or split, variable
.TITLE Action 'e'
~X1Format:   evsabc...

The 'e' action allows a variable to be split into fields, and
assigned to a number of other variables. Parameter 'v' is the name
of the source variable, 's' is a character used to separate the
fields in the source variable, and abc... are the target variables
to receive the fields. If the character 's' is ommitted, the
fields are assumed to be separated by spaces. There is a list
of ~Freserved characters~E which cannot be used as separators.

    ex:abcd           - splits 'x' on ':' into a,b,c and d

If 'x' contained 'one:two:three:four' then 'a' would become 'one',
'b' would become 'two' etc.
~G
The opposite effect to the expand action is to pack the values of
a number of variables in a variable, with a separator between
them. This can easily be accomplished by the form:-

   Vv$$as$$bs$$c

Where the values of v,s,a,b,c are as above. This mechanism can be
used to pack a set of variables for storage whilst the variable
names are used for some other purpose. Of course the variable can
be expanded into a set of variables other than the original.
.
.FRAME Frame selection
.TITLE Action 'F' and 'f'
~X1Format:   Fframename{^{hyperfile}}
     fframename{^{hyperfile}}

The 'F' and 'f' actions select a new frame to display.

The parameter specifies the frame name of the frame to be
displayed. If just a frame name is supplied, the frame is assumed
to be in the local hyperfile. If the hyperfile parameter is used,
this indicates that the frame belongs to the specified hyperfile.
If the '^' character is present without a hyperfile, the primary
hyperfile (that named on the command line) is assumed.
The home frame of a hyperfile can be selected with the form:-

   F^hyperfilename

The home frame of the current hyperfile is selected with the form

   F
~G
The lowercase form of the action modifies the backtrack processing
so that the frame replaces the last frame reference on the
backtrack list, rather than being added to the list. This is used
to step through related frames when it is clear that the user is
reading them through, and where it is not necessary to stack the
frames on the backtrack list. Also, whilst the uppercase form
causes a currently executing script to be cleared, the lowercase
form does not. The example shows an action which will step to the
next frame in the hyperfile, without retaining the previous frame
reference.

   f+

The '+' modifier is only applicable to the 'F' or 'f' action.
An extended form of the '+' modifier allows selection of the
next matching or unmatched frame:-

  F+1     -  next matching frame
  F+2     -  next unmatched frame

If you have chosen to have duplicate frame names in your
hyperfile, the special form:-

   F+frame name

can be used. This looks for the frame from the current frame
onwards. It can therefore be used in the action string of a
reference in a frame to look for the next occurrence of the
frame name after that frame - for when the hyperfile is split
into sections, or can be used to step through all frames of a
particular name by using 'Fframe name' for the first and
'F+frame name' for the rest.

The '-' modifier is used to step to the previous frame in the
hyperfile, and to 'wrap' to the last frame from the first.

    F-
.
.FRAME Graphic screen display
.TITLE Action 'G' and 'g'
~X1Format:   Gfilename
     g{filename}

The 'G' and 'g' actions display a graphic or text screen from a
file in BLOAD format. The 'g' variant does not reset the screen
mode after display, so that graphic screens can be displayed one
after the other with no lack of continuity. The 'g' action with
no parameter resets the display mode to the default text mode,
which otherwise takes place the next time the frame display is
refreshed.

The formats of display supported are listed in the component
operation guide. BLOAD images, tagged BLOAD images and .PCX
images of various forms are supported.
~G
The file type is auto-sensed. The correct adaptor type is assumed
to exist and is not tested, apart from text mode screens, where the
correct screen address is used for the adaptor type.

After display the mouse may be used to select a zone on the screen,
or a character may be pressed to choose an option if no mouse is
available. The character and zone mappings are defined in a special
form of MENU, and selected using the ~Fzone selection~E method.

The palette information is ignored if the filename ends in '-'. eg.

         Gwithpal.pcx-

will display the file withpal.pcx, which has palette information,
without the palette information being interpreted. Note that
version 5 corrects a bug in the interpretation of the palette
information when this is utilised.
.
.FRAME Notepad maintenance
.TITLE Action 'H' and 'h'
~X1Format:   H{string}
     h{string}

The notepad, as well as being maintained by the INS and DEL keys,
may also have data added and removed by the 'H' and 'h' actions.
The items on the notepad would normally be action specifications,
although it is possible to store other data on the list for
selection for other purposes. These actions cause the notepad scan
pointer (used by !R) to be reset.

The 'H' action by default requests a comment string which is
associated with the reference when it is listed. This can be
suppressed using the ~FO*8 option~PFextended options~E flag.

     HFframe two       - adds frame reference for 'frame two'

     hNHelp            - removes all note references for 'Help'
.
.FRAME Select next input field
.TITLE Action 'I'
~X1Format:   I
         Ix

The 'I' action is specific to frames containing input fields. This
action is used in an input field action string to select the next
input field after input is complete on that input field.

If a parameter is supplied as in the second format above, the
CURRENT input field is reselected. This is used where an input
field is validated in a script, and has to be re-entered if in
error.

~X1See also: ~FInput field~E
.
.FRAME Insert text
.TITLE Action 'i'
~X1Format:   istring

The 'i' action is used to insert text in the current frame display.
The string can contain formatting flags, but must not contain any
reference flags. It is usual to start with ~~X and ~~Y flags to
position the text cursor for writing the string.

This action can be used to update information on the screen
without redisplaying the whole frame text.

    Y&H;i~~Y1~~X60$$5~~L25

will update the time displayed at line 1 column 60 and re-park
the text cursor.

This action should be used with care, as it is easy to corrupt
the screen display if used incorrectly.
.
.FRAME Jump within script
.TITLE Action 'J' and 'j'
~X1Format:   Jlabel
     jclabel

The uppercase form 'J' is an unconditional branch, and transfers
control to the script ~Flabel~PFLabel in script~E denoted by the parameter.

   Jstart

Branches to the line containing 'Lstart' in the script. If the
label does not exist in the script, the jump does not take place,
and processing continues with the next line in the script.

The lowercase form 'j' is a conditional jump, and is followed by
a letter denoting the condition upon which a jump will occur,
followed by the label to which a branch will be made if the
condition is set. See ~Fconditions~E.
.
.FRAME Set key mapping
.TITLE Action 'K'
~X1Format:   Kksactionstring

The 'K' action maps a keyboard key to an action string. This
action is then available from a frame display (not from paged
displays). When the key is pressed, the action is performed.

Function keys and printable ascii characters may be mapped
(subject to them not conflicting with HyperShell metacharacters).
The key to be mapped is specified by the following notations:-

   K#xstring       Character x
   KFnstring       Function key n
   KSnstring       Shift/function key n
   KCnstring       Ctrl/function key n
   KAnstring       Alt/function key n

Function key 10 is indicated by n = 0.
~G
~X1Example:

    K#hNHelp      - map 'h' key to global note 'Help'

    KF1F^HOME     - Map F1 key to move to HOME hyperfile

Unshifted function keys equate to the main control menu actions,
and mapping them changes the actions for the main menu. This can
be used to disable certain control menu options. The option text
for the main menu can be set using the special form:-

    KMnstring      - set menu option text n to string
~G
The K action is also used for mapping strings and actions to
certain ~Fheadings and control keys~PFControl key mapping~E, using the form

    KHnmapping     or     KGnmapping

~X1Example:

    KH4Q          - map ESCape to action 'Q' to quit HyperShell

The complete set of key and heading mappings can be reset at any
time by the special option action

    O#

This is useful for inclusion at the start of the SETUP script in a
hyperfile, to avoid confusing key mappings being inherited when a
hyperfile is referenced from another.

~X1See also: ~FDo mapped key~E
.
.FRAME Do mapped key
.TITLE Action 'k'
~X1Format:   kks

The 'k' action takes a key specification as for action K and
performs the action mapped to the key specified.

This action is used where an action is both mapped to a key and
tied to a reference or a menu selection.

     kF1           - do action mapped to Function key 1

     k#h           - do action mapped to 'h' key

~X1See also: ~FSet key mapping~E
.
.FRAME Label in script
.TITLE Action 'L'
~X1Format:   Llabelname

The 'L' action does not do any processing, but indicates a line in
a script to which jump actions can branch. The 'labelname' is the
name used as the target of a ~Fjump statement~PFjump within script~E.

    Lrepeat         - label 'repeat'

One of the traditional problems with programming is the endless
loop. To help diagnose this sort of problem, a trace can be
performed by setting ~Foption flag 7~PFoptions~E. If this is set, the script
stops at each label it executes, showing the label name.

    O71

If tracing is not enabled, pressing the ESCape key will stop and
display the label. Any key will resume the script, or pressing ESCape
again will stop the script.
.
.FRAME Load named variable
.TITLE Action 'l'
~X1Format:   lvnamed

The 'l' action is used to load a named variable with a string
value. ~FNamed variables~E can be used instead of the single letter
variables to hold information for expansion in text or in an action.

Parameter v is a single letter variable and 'named' is the name of
the named variable. The contents of the variable v are loaded into
the variable 'named'. Note that the name can be supplied by an
action modifier or by the expansion of a variable token, including
that of the same or another named variable.

    ltTime of day    - loads variable 't' to variable 'Time of day'

~X1See also: ~FNamed variables~E, ~FSet variable~E, ~FSet Named Variable~E
.
.FRAME Popup menu display
.TITLE Action 'M' and 'm'
~X1Format:    Mmenuname
      mmenuname

This action performs the action resulting from selection by the
user from the named menu. The uppercase form is used for global
menus and the lowercase form for local menus, where a local menu
is firstly looked for, with a global menu being looked for if a
local menu is not found. A menu action, and a menu action modifier,
may have special parameters added to select from the menu by means
other than interaction.

     mtype

~X1See also: ~FMenu parameters~E
.
.FRAME Popup note display
.TITLE Action 'N' and 'n'
~X1Format:   Nnotename{params}
     nnotename{params}

The action 'N' pops up the named note, and waits for a key/button
press before clearing the note. The uppercase form applies to
global notes and the lowercase form applies to local notes, where
a note local to the frame is firstly looked for and a global note
accessed if the local note cannot be found. Notes can contain
~Freferences~E just as frames do, and these will be actioned if
selected.

   Nexample note

~FParameters~E can be supplied on a note action.
.
.FRAME Option setting
.TITLE Action 'O'
~X1Format:    O{*}os

The action 'O' is used to set HyperShell control options and colour
schemes. The variants are as follows:-

Ons       - Set option 'n' to 's'
O*ns      - Set extended option 'n' to 's'
OXfb      - Set colour scheme 'X' to foreground 'f' on background 'b'
OXnn      - Set colour scheme 'X' to atrribute nn
O*Xx      - Set application option 'X' to 'x'

~FOptions~E and ~Fextended options~E control the operation of
HyperShell. Parameter n is the option number and s is the setting.
Some options have a set of flags values which should be added to
give the option value, others have a value to represent a funtion.

Individual flags can be set and cleared using the forms:-
    On+f  and On-f

Eg.  to switch on multiple search string support:-  O*8+4
~G
~FColour schemes~E are the highlighting schemes used for various
purposes in HyperShell. They are set to a two character colour
setting consisting of the foreground and background ~Fcolours~PFcolour codes~E.
Note that the brighter 8 colours are used for the background
scheme if blinking is required.

   ONyG      - set note references to bright yellow on dark green

The colour scheme can now be specified as a numeric attribute
value, as obtained using the &oX function.

This value is equal to the colour number of the background
colour times 16 plus the colour number of the foreground colour.
Colour numbers are 0 thru 7 (or 8 thru 15 for the bright
version, or blink in the case of background).

~FApplication options~E are character settings used to control a
HyperShell application, and can act as ~Fcondition codes~PFconditions~E
These are set using the form

  O*Xx

Where X is the application option name of 'A' thru 'Z', and 'x'
is the character value assigned to that option. The option is
reset using the form 'O*X'.
.
.FRAME Printer output
.TITLE Action 'o'
~X1Format:     ostring

The 'o' action prints the supplied 'string' to a route specified
by the printer option. The valid values, along with their routes,
are as follows:-

   0 - Display on bottom line
   1 - Print to printer
   2 - Send to standard output
   3 - Send to standard 'AUX' (e.g. RS232)
   4 - Send to 'output file' (that opened by action 'w')

If an invalid route is specified, output goes to the bottom line.
The printer is enabled by using '-p' on the command line, or by
issuing the action 'O51' to set option 5 to 1. Other routes are set
using 'O5n' where n is one of the above. The 'o' action adds a
carriage return and a line feed character to each line supplied.
~G
    oLine of text          - output line of text to output route

To output a control code to the printer, such as a form feed, the
string function &Cnn can be used:-

   o&C12

CAUTION: It is wise to warn the reader to have the printer ready
.
.FRAME Popup message
.TITLE Action 'P'
~X1Format:    Pmessage

The 'P' action pops up a flashing 'message' at the current mouse
cursor position, and awaits a key or mouse button depression
before 'popping down'.

   PHello there!

If a null string is passed as a parameter, an asterisk will flash
in the bottom right hand corner of the screen. This can be used as
a pause to await a key depression from the user before continuing
with a series of actions.
.
.FRAME Display message
.TITLE Action 'p'
~X1Format:    pmessage

The 'p' action displays a 'message' at the bottom of the screen,
and continues without waiting for any inputs.

   pThis is a long message to stay on the screen

If no parameter is supplied to p, it clears any message currently
on display.
.
.FRAME Quit HyperShell
.TITLE Action 'Q'
~X1Format:    Q{exit status}

This action is used to exit the HyperShell program. If a parameter
string is given, its numeric value is used as the exit status for
the HyperShell program. This means you can use hypershell in batch
files to control the flow, just as with the 'ask', 'choose' etc.
type of programs which set the exit status to be tested with the
'IF ERRORLEVEL' statement. It is also possible that you may wish
to return information to a program that has invoked HyperShell
directly.

     Q1                    - exit with status 1
.
.FRAME Quit script
.TITLE Action 'q'
~X1Format:    q

This action cancels any current script being executed. It can be
used to abort a script if an error situation occurs.
.
.FRAME Formatted read
.TITLE Action 'R'
~X1Format:    Rsabc..

The 'R' action allows a line to be read from the input file
(opened via the 'r' action), split into fields separated by the
character 's', and assigned to a number of variables (abc etc).
If the character 's' is ommitted, the fields are assumed to be
separated by spaces. Separators can be any non-alphanumeric
character which can be supplied at this point in the action string.

When the end of the file is reached, no assignments are performed
and the error status is set.

    R:gja            - reads the next line from the file
                       and splits it on ':' characters into
                       variables g, j and a.

~X1See also: ~FOpen/close input file~E
.
.FRAME Open/close input file
.TITLE Action 'r'
~X1Format:     r{filename}

This action is used for opening or closing an input file dedicated
to applications use. If a parameter is supplied, it contains the
name of a file to open for input. If no parameter is supplied, the
input file is closed. The file opened via this action can be read
by the action modifier '!' or by the action 'R'. Note that on
opening an input file, any already open input file will be put in
suspension until the file is closed, at which time the original
file will again be available for reading. There can only be two
suspended input files.

     rDATABASE.DAT            - open DATABASE.DAT for reading

~X1See also:- ~FFormatted read~E
.
.FRAME Execute script
.TITLE Action 'S' and 's'
~X1Format:    Sscriptname

The 'S' action executes a named script. If a script is currently
being executed, it is cleared prior to running the specified
script. The 's' action looks for a script local to the frame,
and if not found looks for a global script.

       SShow price         - run script 'Show price'

~FScripts~E can be appended to add ~Fsubroutines~PFcall subroutine~E.

If a script calls another script, the first script is cancelled.

~FParameters~E can be supplied on a script action.

~X1See also:- ~Fscripts~E, ~FParameters~E
.
.FRAME Display text file
.TITLE Action 'T'
~X1Format:    T{filename}{#page}{/search string}

The 'T' action (Type file) page displays the named text file.
If no filename is supplied, reentry to a file display that has
been interrupted is assumed. The paged display highlights any
references embedded in the text file, unless the ~Fverbatim~PFOptions~E option
is set. If the ~F8 bit filter~PFOptions~E is set, the top bit is cleared on all
characters displayed (This is used for certain word processor files).

If a search string is specified, the string is located and the page
containing the string is displayed, with the line containing the
string highlighted. If a page number is specified, the display
locates at the page number, and is a search string is also specified
any line containing the search string is highlighted.

     Tmanual.txt           - display file 'manual.txt'
     Tcatalog.dat/chair    - display file and search for 'chair'
     Tcatalog.dat#8        - display file at page 8
     Tcatalog.dat#8/chair  - display at page 8 and highlight 'chair'

A number of function and control keys are supported:-

   F1 or ?         Help
   F2 or #         Request page number and go to page
   F3 or Pg Up     Go to previous page
   F4 or Home      Go to start of file
   F5              Search for next occurrence
   F6 or /         Request search string and perform search
   F7              Redisplay current page
   F8 or End       Go to end of file
   F9 or RETURN    Suspend typing, allowing subsequent return
   F10             Close file and exit typing

   Ctrl-Right      Scroll Right to view text off screen
   Ctrl-Left       Scroll screen to left
   Ctrl-Home       Cycle text interpretation filter
   ESCAPE          Exit typing and cancel script
   Pg Dn or other
    unmapped key   Go to next page
~G
The RETURN key, if over a highlighted reference, selects the
reference, otherwise it returns to the current frame display,
and permits subsequent return to viewing of the file by use of
the 'T' action with no parameter. A further T action, supplying
a parameter, will close the file on display and start a new one.
If action 'T*' is given when a Typed file is current (ie. RETURN was
pressed from a Tfilename display), it closes the current Typed file,
so that it can be used for other purposes, and stops the T action
from re-entering the file display.

References selected from the text will be acted on. Certain
references will have a 'T' action appended so that viewing of
the file will resume after the action has been performed.

The F6 or '/' key will prompt for a search string, and search
forward  through the file for that string, stopping at the page
containing the string and highlighting any lines containing the
string. A ~Fpattern match~E search can be specified by starting the
search string with the '^' character. Further occurrences of the
string can be located by pressing F5.

The F2 or '#' key will prompt for a page number, and will then
locate and display the page.
.
.FRAME File popup note
.TITLE Action 't'
~X1Format:    tfilename

The 't' action displays the contents of a file as a popup note, the
filename having an explicit extension or a default implicit extension
of '.NTE'. The file notes can contain the same as normal ~Fnotes~E,
and can contain references which can be selected. The file note is
used for a number of purposes, and usually indicates that the note
is less permanent than one included in the hyperfile. It could, for
instance, be a scratchpad note created by the HyperShell user.

If a text line in a note file starts with the '.' character, that
line and the remaining lines are not displayed.

     tprices             - pops up note file PRICES.NTE

~FParameters~E can be supplied on a file note action.
.
.FRAME Set variable
.TITLE Action 'V'
~X1Format:    Vxstring

The 'V' action allows a variable 'x' to be set to a 'string'. There
are 52 applications variables named 'a' to 'z' and 'A' to 'Z'.
There are a few system variables that may be set using this command
also, although the numeric ones cannot be changed. ~FVariables~E can
hold any string value, and can also hold numeric data as a numeric
string. Variables can be expanded into the frame text display, a
note display, or into an action string, by specifying the variable
substitution token '$$x' where x is the variable name.

     VnJohn Smith     - set variable 'n' to 'John Smith'

The 'named' variables described under the 'l' action may not be set
using this action.

~X1See also: ~FTest variable~E
.
.FRAME Test variable
.TITLE Action 'v'
~X1Format:    vxstring

The 'v' action compares the variable 'x' against the 'string',
setting condition codes to reflect the result of the comparison.
A lexical comparison is performed, unless the comparand string
starts with a numeric digit or a minus sign, in which case an
integer numeric comparison is made. A substring search of both
operands within each other. The resulting ~Fcondition codes~PFconditions~E can be
used in the 'j', 'a' and 'z' actions, and other places.

      vnSmith;jcSMITHS  - jumps to SMITHS if 'n' contains 'Smith'

Pattern matching is performed during a variable comparison if
variable '~~' is set. If the supplied pattern starts with a '^'
character, the variable is compared against the supplied pattern
using a ~FPattern Match~E process, otherwise a case sensitive
comparison is performed. If the comparison succeeds, condition code
'm' is set, else condition code 'f' is set. If variable '~~' is NOT
set, the condition code  'f'  will  be set in ALL CASES (even when
condition code 'e' is set).


To test a named variable, it first has to be loaded into a single
letter variable using the form:-

     Vx$$(named)

This may then be used in the test:-

     vxtest value

~X1See also: ~FSet variable~E
.
.FRAME Write record to file
.TITLE Action 'W'
~X1Format:     Wstring

The 'W' action writes the parameter string to the output file
opened via the 'w' action.

     WRhododendron      - writes 'Rhododendron' to file

 A line can be formatted to contain the
values of variables by simply specifying the variable expansion
tokens at the required place in the line. Thus to write a line with
variables a,b,c in it separated by colons, we specify:-

   W$$a:$$b:$$c
.
.FRAME Open/close output file
.TITLE Action 'w'
~X1Format:    w{filename}
      w{filename+}

This action is used for opening or closing an output file for
hyperfile applications to use. If a parameter is supplied, it
contains the name of a file to open for output. If no parameter is
supplied, the output file is closed. If a suffix of '+' is added,
an existing file is opened for extension. The file opened via this
action can be written to using the 'W' action. If the file cannot
be opened, an error status is set.

     wprices.dat    - opens file PRICES.DAT for writing

On opening an output file, any already open output file will be
put in suspension until the file is closed, at which time the
original file will again be available for writing. There can only
be two suspended output files.
.
.FRAME Execute program
.TITLE Action 'X' and 'x'
~X1Format:    Xcommand line
      xcommand line

The 'X' action executes the program and parameters supplied in the
parameter string, and returns to HyperShell when the program
terminates. The uppercase form waits for a key press before
redisplaying the current frame, the lowercase form returns
immediately to the display. The system variable '^' is set to the
numeric exit code of the program.

     Xpayroll week 1   - runs program 'payroll' with parameters

Care should be exercised when specifying the program invocation,
as certain errors will 'crash' the computer and require a reboot.
If in doubt, use the 'D' action, which is safer. The X actions are
more efficient in speed and memory utilisation, however, and the
exit code of the executed program is always available.
.
.FRAME Clear status
.TITLE Action 'Y'
~X1Format:    Y

The 'Y' action does nothing, apart from reset the error status to
0. It is also used to 'throw away' the results of an action
modifier.

If the special system variable (`) is used, the Y action
should be used to reset the error status so that the error
action mapped to the variable is performed on an error.
.
.FRAME Refresh frame display
.TITLE Action 'y'
~X1Format:    y{c}

The 'y' action refreshes the current frame display. If a
parameter 'c' is supplied, and the frame occupies more than
one screenful, the action has the following effects:-

      y              - display first page of frame
      y#             - redisplay current page of frame
      y-             - display previous page of frame
      y+             - (or any other character than '-' or '#')
                       display next page of frame or first
                       page if at end
.
.FRAME Unless condition
.TITLE Action 'z'
~X1Format:     zcaction

The 'z' action works in the same way as the ~Fconditional action~E
does, but the action is only performed if the condition is FALSE.

     vn23;zlJGREQ - jumps to GREQ if 'n' not less than 23
.
.FRAME Extended action codes
.TITLE Action codes 'Z'
The 'Z' code introduces an 'extended' action code. This is one
where a second character denotes the action to be performed.

As action modifier codes are required in the second or third
character position, only the third character position is
available with these action codes. This does have advantages
in some cases.
.
.FRAME Specified autoreference
.TITLE Action code 'ZA'
~X1Format:    ZArreference:action
      ZArreference

The 'ZA' action sets up an autoreference specification. The 'r'
parameter is the reference type, and can be one of the reference
flags A,F,f,M,m,N,n,S,s,t. action is the action string to be
mapped to the reference. If the action part is ommitted, as in
the second format above, the action string defaults to just
'rreference'. When the autoreference is applied, instances of
string 'reference' are replaced by the string:-

    ~~rreference~~Paction~~E    - for first format

    ~~rreference~~E        - for second format

To perform autoreferencing, the options 4 and *4 should be set
appropriately (4 should be 2 or 3, *4 should be 0 or 1).

This form of autoreferencing can be used for glossary references
to global notes, or for ~Falternative hypertext~E referencing.

Examples:

     ZANTSR        - sets autoreference for note 'TSR'

This sets note reference flags on all occurences of the string
'TSR' in the text.

     ZAAQuit:Q     - sets up an action autoreference

This maps the 'Q' action to all occurrences of the word 'Quit'
in the text.
.
.FRAME Search string autoref
.TITLE Action code 'Za'
~X1Format:    Zarssssssssssssssssssssssssss:action

The 'Za' action sets up an autoreference specification which
causes the last search string to be autoreferenced. The 'r'
parameter is the reference type, and can be one of the reference
flags A,F,f,M,m,N,n,S,s,t. action is the action string to be
mapped to the reference.

When the autoreference is applied, instances of the search
string are replaced by the string:-

    ~~rsearchstring~~Paction~~E

To perform autoreferencing, the options 4 and *4 should be set
appropriately (4 should be 2 or 3, *4 should be 0 or 1).

THIS ACTION MUST ONLY BE SPECIFIED ONCE. The search string will
be maintained as an autoreference. Beware of specifying a very
common search string eg. 'e', otherwise the references will
overrun the display.
.
.FRAME Sound Bell
.TITLE Action code 'ZB'
~X1Format:    ZB

The 'ZB' code causes the audible warning device to be deployed.
This usually emits a 'beep' sound.

~p    ~APress this if you haven't heard one before~PZB~E
.
.FRAME Blink enable
.TITLE Action code 'Zb'
~X1Format:    Zb1
      Zb0

The 'Zb' action changes the way the text screen handles the 'blink'
attribute. The settings are as follows:-

  Zb1       - Blink characters with high bit set (lowercase colours)
  Zb0       - High intensity background for characters with high bit

This action may be used on various display adaptors to change the
appearance of the text, and allow high intensity background colours
to be set.

~X1CAUTION:     THE ADAPTOR IS LEFT IN THE CURRENT STATE ON PROGRAM EXIT
.
.FRAME Do control menu
.TITLE Action code 'ZC'
~X1Format:    ZC

The 'ZC' code causes the HyperShell control menu to be presented
for selection. It is by default mapped to the ESC key.
.
.FRAME Set configuration string
.TITLE Action code 'Zc'
~X1Format:    Zc

This action takes a configuration string as found in the
HYPSHELL.CFG file, and applies it. This is equivalent to the #K
action in HI.EXE, and does not free memory for previously
configured instances of that configuration string.
.
.FRAME Delete named variables
.TITLE Action code 'ZD' [G]
~X1Format:    ZDpattern

The ZD action deletes all named variables conforming to the
given pattern. The pattern string is as described under the
~FPattern match~E rules.

NOTE: AT LEAST ONE NAMED VARIABLE MUST REMAIN AT ALL TIMES !!
.FRAME Exit subroutine
.TITLE Action code 'ZE'
~X1Format:     ZE

    The 'ZE' action returns from a subroutine called in a ~Fscript~PFscripts~E
    by the ~FCall subroutine~E action.

    If no subroutine is in effect, no return is made.

.
.FRAME Set footer depth
.TITLE Action code 'ZF'
~X1Format:    ZFnn

The 'ZF' action sets the depth reserved for the ~Ffooter~E section
for when conditional lines are included in the footer. The depth
should accommodate the footer text with the most lines.

This action is used in the SETUP script, if required. It is not
necessary where the footer is of fixed content, as it will be
determined automatically when the header is loaded.

      ZF4         - set footer depth to 4
.
.FRAME Get mouse coordinates
.TITLE Action code 'ZG'

The 'ZG' action causes the mouse coordinates to be read into the
variables used by the ~Fzone selection~E operation normally after
a graphics display.

These variables can be accessed using the functions &X and &Y,
or a zone selection could be performed based on the new values.
.
.FRAME Special graphic selection
.TITLE Action code 'Zg'
~X1Format:    Zg
      Zgx

The 'Zg' action will cause the mouse to be used for selection from
the screen currently on display. If a parameter is supplied as in
the second format, the screen is assumed to have a high vertical
resolution (greater than 200) when calculating the mouse
coordinates.

This is used where some external program is used to display the
graphic screen, or possibly when a further selection is needed
from a screen displayed using the 'g' ~Fgraphic screen display~E.

.
.FRAME Hold line for return
.TITLE Action code 'ZH'
~X1Format:   ZH

The 'ZH' action causes the current line number to be held in
the subroutine call stack, permitting a return to be made to
the current line using the ~FExit subroutine~E action. This is
used as an alternative method for loop constructs:-

   -- open file
   rfilename.ext
   -- read file
   ZH;Y;R,abc
   jsEOF
   P$a $b $c
   -- loop back to read
   ZE
   LEOF
   r
   q
.
.FRAME Quick conditional
.TITLE Action code 'ZI'
~X1Format:    ZIexpr;action . . .

The 'ZI' action, pronounced 'if', allows a single line conditional
statement to be coded. The 'expr' represents a numeric expression
as used in the ~FExpression Evaluation~E action modifier, but
without the introductory '=' sign. If the expression evaluates to
TRUE (having a value other than 0), then the remaining actions of
the multiple action are performed, otherwise they are ignored.
Condition codes are not affected by this action, unless the
combined string compare and condition truth test (quotes) is used.

With the extended ~Fexpression evaluation~E capabilities, this makes
multiple conditions easy to specify. For example to test if variable
'x' is in the range 10 to 15 inclusive, and print a message if not,
the following multiple action is coded.

   ZI(x < 10) ! (x > 15);pValue outside permitted range

.
.FRAME If number
.TITLE Action code 'Zi'
~X1Format:    Zinumber;action . . .

The 'Zi' action is similar to the ~FQuick Conditional~E action. It allows
a single line conditional statement to be coded. The 'number' is any
modifier which returns a numeric result. A non-zero result will cause
the remaining actions of the multiple action are performed, otherwise
a zero result will cause them to be ignored.

Condition codes are not affected by this action.

Example:-

    Zi&L$$F;VL$$F

If the length of variable F is greater than 0, load it to variable L.


.
.FRAME Call subroutine
.TITLE Action code 'ZJ'
~X1Format:     ZJlabel

The 'ZJ' action acts like the ~FJump within script~E action, only the
current position in the script is retained so that it can be
returned to using the ~FExit subroutine~E action. If the label does
not exist, no branch is made, but the position is marked so that a
return can be made.

Subroutines can nest up to 10 deep.

 . . .
 ZJDouble        - branches to subroutine 'Double'
 . . .           - return to here when subroutine exits

 LDouble         - start of subroutine 'Double'
 . . .
 ZE              - exit from subroutine
.
.FRAME Local flag toggle
.TITLE Action code 'ZL'
~X1Format:    ZLn{s}

The 'ZL' action toggles the frame local flag 'n', and causes the
display to be refreshed, unless the refresh suppression character
's' is specified. The flag 'n' has a value of '0' to '9' or one
of the special local flags '/' or ':'.

This is used for ~Ainline text expansion~PZL3~E using a reference
of the form:-

   ~~Ainline text expansion~~PZL3~~E

~h3     Inline text expansion is used to provide additional information
~h3     hidden within the text until a reference is selected. This is
~h3     useful where an expert would not want to read mundane details
~h3     which a novice would require. The local flag is usually used
~h3     for this, although a ~Fglobal flag~PFglobal options~E can be used where an overall
~h3     expansion of text for a novice is required.
.
.FRAME Local flag indicator
.TITLE Action code 'Zl'
~X1Format:   Zlc{i}

The 'Zl' action is used to select which of the ~Flocal flags~E will
cause an indicator to be displayed in the ~Fcontents list~E.

The 'c' parameter is the local flag code to be used. The optional
'i' parameter is a single character indicator which is displayed
next to the key map box in the contents list.

~X1Example:

Zl:

This causes the default indicator '√' to be shown in the contents
for frames which have been visited.
.
.FRAME Set 43 or 50 line mode
.TITLE Action code 'ZM'
~X1Format:    ZM{nn}

The 'ZM' action sets the video mode for the adaptor.

   ZM3         80 column by 25 line mode (default)
   ZM64        80 column by 43 or 50 line mode

This should only be used with EGA and VGA adaptors. In the 43/50
line mode, depending on the mouse driver and adaptor, different
degrees of control are available over the mouse cursor. You may
find that it is not possible to properly use the extra lines.
Using the -m flag on the command line may allow you to move the
cursor below line 25 using keyboard control.

All paged lists and the typed file display make use of the extra
lines.  Frame text also makes use of it, provided the footer has
not truncated it at an earlier line. The number of lines is
returned by function call &R25.
.
.FRAME Set message line
.TITLE Action code 'Zm'
~X1Format:    Zmnn

Messages and prompted input is usually restricted to line 25, or
the bottom line of deeper displays. This action can be used to
change the message and input line to another line. Applications
can then utilise different screen formats with messages appearing
on, for example, the second line.
.FRAME Save notepad
.TITLE Action code 'ZN'
~X1Format:    ZNfilename.ext

The 'ZN' action saves the current notepad, variables and current
frame name, as selected using option 0, in the named file.

  See   ~FOptions~E

The saved file can subsequently be run as a script, using the
'c' action, to reinstate the notepad and other items.

  See   ~FCall script file~E
.
.FRAME Print frame
.TITLE Action code 'Zo'
~X1Format:     Zo                             (HL.EXE ONLY)
       Zot                            (HL.EXE ONLY)

The 'Zo' action prints the current frame text to a route specified
by the printer option (O5) as for the 'o' action - see ~FPrinter output~E.

If an invalid route is specified, there is no output.

If the 't' parameter is supplied, the frame name and title are
printed before the frame text, and a blank line printed after.

This action is only available in the HL.EXE component. The HI.EXE
component has the #P action which does a similar thing.

CAUTION: It is wise to warn the user to have the printer ready
.
.FRAME Preload hyperfile
.TITLE Action code 'ZP'
~X1Format:    ZPhyperfile

The 'ZP' action causes a hyperfile to be loaded without any frame
being displayed from it. This is useful to load a set of hyperfiles
during the SETUP script, to permit searches to be made across them.

     ZPextra             - preloads EXTRA.HYP
.
.FRAME Recall saved screen
.TITLE Action code 'ZR'
~X1Format:    ZR

The 'ZR' action displays the screen that was saved at startup, if
the '-s' flag was specified on the command line. If this flag was
not specified, nothing happens.

The frame is redisplayed when any key is pressed.
.
.FRAME Reset to full screen
.TITLE Action code 'Zr'
~X1Format:    Zr

The 'Zr' action is used to reinstate the full screen mapping
after a window has been defined within the screen using the
~Fbox draw~E reference flag, usually through a 'i' action.
.
.FRAME Set environment variable
.TITLE Action code 'ZS'
~X1Format:    ZSenvironment string assignment

The 'ZS' action causes an environment variable to be set, which can
be used elsewhere in HyperShell using the ~Fenvironment variable~E
modifier, or passed to a program invoked from HyperShell, such as
dBASE III, which can access the variable to obtain parametric
information.

     ZSNAME=FRED JONES   - equivalent to SET NAME=FRED JONES
                           on the DOS command line.
.
.FRAME Take copy of screen
.TITLE Action code 'ZT'
~X1Format:   ZT

The 'ZT' action takes a copy of the current screen display.

The whole screen is saved to the screen save area
(and overwrites that set up by the -s flag, if one was specified).

The saved screen is displayed using the ~FShow saved screen~E action.

This may be used before a ~Fsubwindow~PFBox draw~E is drawn, to allow the
subwindow to be 'popped down' after use.

~X1CAUTION: These actions can be used for other purposes, but care must
be taken not to confuse the user with false reference mappings.
.
.FRAME Show saved screen
.TITLE Action code 'Zt'
~X1Format:   Zt

The 'Zt' action shows the screen display saved by a previous
~FTake copy of screen~E action. If no saved screen is available,
this action acts as a 'clear screen' command.

The whole screen is overlaid by the saved screen save area
(or the one that set up by the -s flag, if one was specified).

A number of subwindows can be drawn, and cleared again afterwards
using the Show saved screen action.

~X1CAUTION: These actions can be used for other purposes, but care must
be taken not to confuse the user with false reference mappings.
.
.FRAME Unget key code
.TITLE Action code 'ZU'
~X1Format:    ZUc{ttt}

The 'ZU' action is used to place a character in the key input
so that the action mapped to that character will be performed
as though the key had been pressed. This can be used for frame
display inputs, note display inputs, popup request inputs and
graphic display inputs. It cannot be used for popup menus or
for paged lists.

If the ttt parameter is supplied, it is used as a timeout
period in hundredths of a second. In this case, the user is
given the opportunity of typing a character, which will be
used instead of the timeout character. The cursor and tab
keys, and mouse movement, do not count as key presses. The
timeout period starts as soon as input is expected:-

  ZU+300;Fone

Display frame 'one', then timeout with '+' key after 3 seconds.
.
.FRAME Set Named Variable
.TITLE Action code 'ZV'
~X1Format:   ZVnamed=value

The 'ZV' action is used to set a named variable to a string
value. ~FNamed variables~E can be used instead of the single letter
variables to hold information for expansion in text or in an action.

'named' is the name of the named variable. Note that the name can be
supplied in part or in full by the expansion of a variable token,
allowing a form of 'subscripting' for arrays of values.

~X1Example:

    ZVdate=$$4               - set variable 'date' to current date

~X1See also: ~FNamed variables~E, ~FSet variable~E, ~FLoad named variable~E
.
.FRAME Set mouse column
.TITLE Action code 'ZX'
~X1Format:    ZXnn

The 'ZX' action sets the 'x' position of the mouse cursor, namely
the column number, from 1 to 80. The 'y' position, or line number,
stays the same.

      ZX3              - set mouse cursor at column 3
.
.FRAME Set mouse line
.TITLE Action code 'ZY'
~X1Format:    ZYnn

The 'ZY' action sets the 'y' position of the mouse cursor, namely
the line number, from 1 to 25. The 'x' position, or column number,
stays the same.

     ZY15              - set mouse cursor at line 15
.
.FRAME Bitmap sublanguage
.TITLE Action code 'ZZ' [G]

The 'ZZ' action and the reference extensions provide access to this
language. The ZZ action takes the command string as its parameter
string.  The format of the sublanguage command string is as follows:-

    commands^item

'commands' are an ordered sequence of single letter commands.
'item' is the name used to reference the bitmap. This applies either
to a disk file, a member of a library, or a named variable.  The
format of 'item' is filename.ext

A general 'save area', or buffer, is used for bitmaps in transit.
This is used for saving the area where 'popup' items appear, and is
also used for bitmaps loaded for display. It is important to remember
this when considering the sublanguage commands.

The bitmap images are located on character cell boundaries and
are sized in character cells. Character cells are always 8 bits
wide. The cell height is as follows:-

       8  bits for CGA and EGA 640x200
       14 bits for EGA 640x350
       16 bits for VGA 640x480

[1]  ~AList sublanguage commands~PA@C0Sublang~K1~E
.FRAME Get image
.TITLE Sublanguage command G [G]

The G command gets the image from the screen to the general save area

The region on the screen to be copied is marked by using the ZG action
with the mouse positioned at the top left, then positioning the mouse
at bottom right before using the ZZ action to obtain the image.

   screen clip -> general save area

.FRAME Get reference image
.TITLE Sublanguage command C [G]

The region on the screen to be captured is obtained from the last
reference selected. The reference can be a text reference or a graphic
reference. This is used for reference inversion and flashing.

    screen clip -> general save area

.FRAME Write image to file
.TITLE Sublanguage command W [G]

This writes the image obtained using the 'G' command to a file in .HGP
format.

        general save area -> file

.FRAME Read image from file
.TITLE Sublanguage command R [G]

This reads a .HGP format file into the general save area.
(filename = item)

        file -> general save area

.FRAME Save image to memory
.TITLE Sublanguage command S [G]

This saves the image to a named variable with name = item. It
recognises if the image is a compressed image so that it may be loaded
in the correct fashion.

        general save area -> memory
.FRAME Read and save image
.TITLE Sublanguage command V [G]

Read image and store in variable of same name.  This combines the
functions of the R and S commands

        file -> general save area
        general save area -> memory
.FRAME Load image from memory
.TITLE Sublanguage command L [G]

This points the load pointer, which usually points at the general save
area, at the named variable.  It allows a bitmap to be displayed
directly from the variable memory using the P command. (NOTE:
Decompresses image if compressed (as D below))

        point at memory
.FRAME Load and decompress image
.TITLE Sublanguage command D [G]
This loads and decompresses an image (saved with S or X) to the
general save area

        memory -> decompress -> general save area
.FRAME Open library file
.TITLE Sublanguage command O [G]

This opens a library file with name = item  (eg. ZZO^GLIB.HLB) ready
for use with library commands.  The library stays open until either
you open another library or you open an invalid library name to close
it.

NOTE:  YOU MUST SPECIFY THE FILE EXTENSION

    close library if open
    open library file
.FRAME Extract item from library
.TITLE Sublanguage command X [G]

This extracts an item from the library with name = item and store
it as the same name. (eg. ZZX^TEST.CMP)

        library -> memory

.FRAME Soft extract
.TITLE Sublanguage command E [G]

Extract itrm from library if not already loaded

     if memory does not exist, library -> memory

.FRAME Position at mouse cursor
.TITLE Sublanguage command M [G]

Position the top left of the image at the mouse cursor.
.FRAME Position at text cursor
.TITLE Sublanguage command T [G]

Position the top left of the image at the text cursor.
.FRAME Position at box top
.TITLE Sublanguage command B [G]

Position the top left of the image at the box top position. This is
the point specified by ~~a.

.FRAME Put image to screen
.TITLE Sublanguage command P [G]

This displays the current image to the screen.

        general save area (or memory) -> screen

The P command can be made to offset the image downwards a number of
pixel lines by prefixing it with the sequence +n   where n is 0 to 9
(note n can also be one of the characters after 9 in the ASCII set so
+: offsets 10, +< offsets 12 etc.)

This may be used to locate an image precisely on any vertical
position. Example LT+2P^leaf.hgp displays leaf.hgp at the text
position plus 2 pixels vertical displacement.

.FRAME Invert image at pointer
.TITLE Sublanguage command I [G]

This inverts the image currently pointed to. This is usually used
immediately prior to a 'P' operation, but may be used for other
purposes.

1.  If this is done after an L operation (point to memory), then the
stored image will be inverted. A second inversion will restore the
image to normal in this case.

2.  If this is done after a D operation (decompress to save area),
then the transient image will be inverted, and the stored (compressed)
image will not be affected.

        invert (pointer ->) image

.FRAME Wait a while
.TITLE Sublanguage command Z [G]

Wait for 20ms. This is used to introduce a pause for image inversion
flashing etc. A number of Zs can be put together for longer pauses.

.FRAME Play sound sample
.TITLE Sublanguage command H [G]

This plays the current image buffer as a sound sample through
IBMSND.COM driver. The sample must be in HSN format.

        general save area (or memory) -> sound driver

.FRAME Load image as mouse cursor
.TITLE Sublanguage command A [G]

This loads the current image buffer as a mouse cursor

        general save area (or memory) -> mouse cursor

.FRAME Load file as font
.TITLE Sublanguage command F [G]

This loads the current image buffer as a font into the CHARBIOS
buffer.  It requires CHARBIOS to be loaded.

        general save area (or memory) -> font bank

.FRAME Load 16 colour palette
.TITLE Sublanguage command U [G]

Loads current image buffer as a palette (uses .PAL files)

        general save area (or memory) -> palette registers

.FRAME Load 256 colour screen
.TITLE Sublanguage command J [G]

Loads the current image buffer as a full low res 256 colour screen.
This requires that the mode has been set to 19 using the ZM command.

        general save area (or memory) -> screen memory

.FRAME Test CHARBIOS loaded
.TITLE Sublanguage command Q [G]

This tests to see if CHARBIOS is loaded and reports an error if it
is not loaded. Also do not perform further sublanguage commands
in this sequence.

        eg. Put the following in the SETUP script to abort if not loaded

        Y;ZZQ;joLOADED
        PCHARBIOS is not loaded;Q
        LLOADED

Also can be used at the start of sequences if you wish to continue
without actioning sublanguage commands if CHARBIOS is not present.
(Items which rely on it check for it in any case!).

.FRAME Use of graphic memory
.TITLE Graphic save area usage [G]
The commands G,R,S utilise the same memory as popup notes, menus etc.
This means that if you are displaying something in a note, it should
be displayed from a named variable (eg. LTP^picture.hgp) and NOT from
a file, otherwise the popup will be lost and the screen will be
refreshed when it is popped down.  Also, an image to be displayed in a
note should not be compressed, otherwise it will be expanded to the
general save area.

.FRAME Default display command
.TITLE Sublanguage command 1 [G]

This permits the default image display string to be specified

        ZZ1^LTP

.FRAME Auto-purge pattern
.TITLE Sublanguage command 2 [G]

When the program runs out of memory to allocate, it tries to delete
named variables matching a specified pattern.  The default pattern is
\#* which matches all names starting with a '#' character.

It is useful to use lowercase names for graphic resources loaded on a
temporary basis, and then set the following pattern for the auto-purge
operation to delete these if required:-

      ZZ2^[a-z]*
.FRAME Bitmap offset
.TITLE Sublanguage command + [G]

The bitmap display command P normally puts the image to screen at a
character cell boundary. The + command displaces the image
vertically by a number of pixels. For example

  LT+3P^image.hgp

This offsets the image by 3 pixels.

To move a selected image down two pixels and back again, the
following sequence can be used:-

  C+2PZ+0P
.FRAME Graphic hooks
.TITLE Built-in graphic triggers [G]
Font selection - GX hooks

The following are special built-in font setting variables for display
transitions. These are named variables defined using the ZV action to
graphic sublanguage commands.

GXN      - Font for use in popup note
GXM      - Font for use in popup menu
GXT      - Font for use in main text
GXP      - Font for display of popup note

eg. ZVGXT=LF^DEFAULT.UDG

The GXR command is called whenever a reference is selected.
It can be set to invert the reference as an indication that
it has been selected.

eg. ZVGXR=CIPZIP        - invert, pause, invert back

Mouse cursor selection - GM

The following variables are built-in hooks, which should be
defined as for the GX commands above. The sublanguage statements
in this case should set a mouse cursor.

GMx where x is one of the standard reference flag letters -
    A,F,M,S,N or R and causes invocation of the graphic sublanguage
    string when the mouse cursor moves over a reference of the
    appropriate type. The local (lowercase) reference flags are mapped
    to these also.

GMT This is invoked to reset the mouse cursor to that used for open
    text, when the mouse moves off a reference.

eg. ZVGMN=LA^POINT.HMC

See also:  ~FDo bitmap command~E, ~FDo draw command~E
.FRAME Draw sublanguage
.TITLE Action code 'Zz' [G]
Format:    Zzcommands

The graphics drawing sublanguage is provided using the 'Zz' action.
Pixel coordinates are from the top left corner at 0,0. Commands are:-

  cccc   - colour sequence
  X      - exclusive or the following commands
  Hnnn   - set horizontal coord (x)
  hnnn   - set horizontal coord 2 (x) (default is last coord)
  Vnnn   - set vertical coord (y)
  vnnn   - set vertical coord 2 (y)  (default is last coord)
  P      - set coordinates to mouse pixel coordinates
  Ldnnncccc   - horiz/vert lines
        d   = direction
        nnn = repeat
        ccc = colour sequence

  lc     - draw line from coord 2 to specified coord
        eg. draw green line from last graphic position to 200,100
            ZzH200V100lG

  directions
                7  8  9
                 \ | /
               4 -   - 6
                 / | \
                1  2  3

  colour sequence
  -     Colour letters as per HyperShell colour values

        eg. rrr    is three bright red pixels

  -     T   - transparent pixel (leave screen pixel as is)

  -     ,   comma - "carriage return / line feed"
  -     '   quote - vertical "carriage return / line feed"
  -     .   point - "carriage return"
            These allow a sequence of raster lines to be drawn
            in the required direction
.FRAME Parameters
.TITLE passing data into scripts and notes
The actions t,N,n,c,S,s and the @t,@N,@n modifiers can have a
parameter string added in parentheses afterwards as follows:-

   Sscript(parameters)

The string in parentheses is assigned to variable $$\, and can be
used as such in the note or script. In a script, it can be split
up on a separator using action 'e'. If the script is called with:-

   Shelp(contents,12,file.txt)

Then this may be split into variables in a script using the action

   e\,abc...

where a,b,c etc. are the variables to split the string into.
For the above, this would set a = contents, b = 12, c = file.txt

The variables can then be used within the script as parameters.
.
.FRAME Pattern Match
.TITLE Extended string comparison and searching
The Pattern Match operation, used for comparisons and searching,
compares a string against a pattern. The pattern contains literal
characters and various pattern specifying 'metacharacters'.

These metacharacters are as follows:-

 <             at start - match start of string
 >             at end - match end of string
 ?             match any character
 _             match one or more space or TAB characters
 (alt1/alt2)   match alt1 or alt2 (if only one, it is optional)
 [abc]         match 'a', 'b' or 'c'
 [^abc]        match any character but 'a','b' or 'c'
 [x-y]         match any character in range x to y
               e.g. [a-zA-Z] would match any letter
 {             start of word
 }             end of word
 x#            zero or more of the character or subexpression x
 x+            one or more of the character or subexpression x

 *             any string (equivalent to ?#)

 \x            character 'x' (allows metacharacters to be used
               literally)

Examples:-

   [a-zA-Z]#          an alphabetic substring
   [0-9]#             a numeric substring
   (perhaps)          optional substring 'perhaps'
   (cat/dog)(s)       'cat' or 'cats' or 'dog' or 'dogs'
   ((pine)apple/grape(fruit))
                      'apple','pineapple','grape', or 'grapefruit'

    <.FRAME           a string starting '.FRAME'
.
.FRAME Menu parameters
.TITLE Special forms of menu selection
A number of different selection methods can be used to
select items from menus, other by presenting the menu to the
user for selection.

~X1[1]  ~FArray selection~K1~E - to use a menu as an array

~X1[2]  ~FLookup selection~K2~E - to use a menu as a lookup table

~X1[3]  ~FZone selection~K3~E - to use a menu for graphic zone actions
.
.FRAME Array selection
.TITLE Using a menu as an array
Special forms of menu action specification are used to permit
selection of a menu option from global, local and file menus,
specified as actions or dynamic menus. The following form
is used to select a menu choice by index:-

   Mmenuname(nn)

Where nn is a number representing the option number in the menu to
select. If the number is outside the range of the menu, no action
is performed (or is returned for an action modifier), and the error
status is set.

   P@Merror message(4)    - Pops up line 4 of menu 'error message'
.
.FRAME Lookup selection
.TITLE Menus as lookup tables
A menu can also be used as a lookup table. The menu is then
accessed by a specification of the form:-

   Mmenuname[key]

In this case, the lines in the menu section have to be set up in
the following form:-

   key|action

Where key is the key to look up, and action is the action to perform
if a match is found. The '|' character has to immediately follow the
key string for this to work. If the key is not found in the menu, no
action is performed and the error status is set. If the key is found,
the action part is returned as the menu result. The last line of a
lookup table menu can be of the form:-

    *|default action

This action is performed if the key is not found in the other options.
.
.FRAME Zone selection
.TITLE Mapping an action to a selection zone
The form Mmenuname[@] is used for zone selection menus used with
graphic displays. The menu options in this case are set up using
the graphics preparation facilties described in the operation
guide. They can also be set up manually, and have the following
form:-

kXYxy|returnval

where k is the key mapping and XY and xy are the top left and
bottom right corners of the selection zone. Returnval is the
value returned by menu, as usual. XxYy are single characters
equal to ASCII 32 + the column/row number (similar to those
used in ANSI escape sequences on terminals). If a RETURN key
or left mouse button is pressed, the zone coordinates are
searched. If any other key is pressed, the key mappings are
searched.

A default entry can be placed at the end of the menu using an
option of the form:-~G

*....|default action

Because the menu is searched in sequence from to to bottom,
selection zones can overlap, as the selection priority is
determined by the sequence. The zone 'on top' or 'in front'
should come before the one behind. The graphics preparation
facilities build the list from the start, so highest priority
zones should be specified first. Of course, the list can be
edited afterwards if the zones are in the wrong order.
.
.PRINT SECTION 5.
.
.PRINT TITLE
Reference Guide - Action modifiers
.
.PRINT PAGE
.
.FRAME Action Modifier functions
.TITLE Section - Functions to modify actions
The action may have its parameter string supplied indirectly via an
action modifier, or the first character supplied directly and the
rest supplied indirectly. The action modifier argument string may
contain variable tokens, which are expanded prior to evaluation.
The result of the action modifier can optionally be further
formatted via ~Fpattern strings~E. The resulting parameter string then
has any ~Fvariable token specifiers~PFexpansion of variables~E expanded prior to being applied
to the action. Action modifiers are as follows:-

~X1[1]    ~FPrompt Function~K1~E            Ask for string
~X1[2]    ~FRead and Lookup functions~K2~E    From file
~X1[3]    ~FEnvironment variable~K3~E        As SET by DOS
~X1[4]    ~FExpression evaluation~K4~E        Arithmetic
~X1[5]    ~FString functions~K5~E        Miscellaneous
~X1[6]    ~FDynamic menu functions~K6~E        Menus and selections
.
.FRAME Prompt function
.TITLE Modifier code ?
~X1Format:    ?prompt string
      ?prompt string/default

The prompt modifier allows a string to be requested from the user.
'prompt string' is a string which is used as a prompt to the user.
The input response will form the resulting parameter. If the first
character of the prompt is a ':', the input response is not echoed
to the user, allowing passwords and other confidential material to
be input.

     Vn?Enter your name    - loads input string to variable 'n'

A  string  can be provided for editing by appending a string to the
prompt modifier. When this is done, the cursor is placed at the
end of the string ready for editing. This can be used to provide
defaults or to modify the previous value of a variable:-

      Vc?Delete disk/Y

      Vj?Enter name/$$j
.
.FRAME Read and Lookup functions
.TITLE Modifier codes !,!F,!L,!B,!P,!S,!N
~X1Format:     !{F|L|B}{key}
       !Pnnnn
       !{S|N}key

These functions perform read and search operations on the input
file (opened by an 'r' action). The modifier for a file read is

   !F{key}

Where {key} is an optional key string, which is compared against
the start of each record read until a match is found. The
comparison is case insensitive. If '!' or '!F' appears on its own,
it returns the next line read from the input file. Any search
starts immediately after the last record read. The modifier

   !L{key}

Causes the file to be rewound prior to the search taking place.
The EOF status is set if the end of file is reached.
~G
   !Bkey

Provides a very fast search of a text file sorted in ascending
order. The file can be sorted using the DOS SORT command.

The fast search CANNOT be used on compressed files.

   !Pnnnn

Positions at byte position nnnn in file and returns line
starting at that position.

   !Skey
   !Nkey

Searches for 'key' in file, starting at beginning of file for
the !S variant, and at the current record for the !N variant.
The key can be anywhere in the record.
.
.FRAME Directory functions
.TITLE Modifier code !D
~X1Format:     !Dwildcard
       !D

These functions allow the file names of files selected using the
wildcard pattern to be accessed. The wildcard specification is
used first to select the first file matching the wildcard. The
specification without the wildcard is then used to step through
the matching filenames. The EOF status is set when there are no
more files matching the specification.

The directory functions do not affect the currently open files,
and it is possible to open, read and close each file in turn.

~X1Example:

    !D*.HYP            - get first hyperfile name
    !D            - get next filename
.
.FRAME Noted references
.TITLE Modifier code !R and !C
~X1Format:    !{R|C}{key}

The noted references, set up using the INS key or the 'H'
action, can be obtained using the modifier:-

   !R{key}

The {key}, if present, causes the references to be scanned for the
next one starting with the key string. For example:-

   !RF

returns the next frame reference.

Any search or step is taken from after the last reference obtained.
The scan pointer is reset whenever a reference is added or removed
from the list, and can be rewound with a dummy 'remove' action:-

   h

The EOF status is set when the end of the references is reached.

The comment associated with the next reference to be read by
the !R modifier can be obtained using the modifier:-

    !C

eg. to get next comment in 'c' and reference in 'r':-

    Vc!C
    Vr!R
.
.FRAME Environment Variable
.TITLE Modifier code %
~X1Format:    %variablename

An environment variable modifier returns the value of a DOS
environment variable. This variable is set using the SET command
under DOS, or using the ~FSet environment variable~E action in
HyperShell.

     Vf%FORMAT    - load value of 'FORMAT' into variable 'f'

The e.v. was set using a DOS command of the form:-

     SET FORMAT=DDMMYY
.
.FRAME Expression evaluation
.TITLE Modifier code =
~X1Format:     =expression

An expression evaluation modifier returns the result of an
expression. An expression can consist of simple integer arithmetic
operations, boolean expressions, or a combination of both.

An integer expression can involve the simple arithmetic operators
 +,-,*,/,% and can use parentheses to direct order of evaluation.
The % operator returns the remainder of a division.

The expression can involve integer values and alphabetic variable
names (used directly without the $$ token). 32-bit signed integers
are used in the evaluation of the expression.

e.g. to calculate a value and assign it to the variable 'c':-

   Vc=(22*r*2)/7
~G
The arithmetic bit operations ! & and ^ represent OR AND and
EXCLUSIVE OR. For example:-

    2 ! 3    -> 3
    2 ^ 3    -> 1
    2 & 3    -> 2

Boolean expressions can be made up from the following operators,
each returning a 1 if true or a 0 if false.

   = or ==    equality of comparands
   ~~=        inequality of comparands
   < > <= >=    left operand less than, greater than, less than
        or equal, greater than or equal
   #c        truth of ~Fcondition~PFConditions~E 'c'
   "xstring"c    combined variable comparison and condition truth
~G
Boolean conditions can be combined using the bit operators to
form compound conditions:-

   (a == 3) ! (a == 4)     evaluates true if a = 3 or 4

The condition flags are set after an expression evaluation as
though the result had been compared against zero. For an arithmetic
evaluation a negative result is tested using the condition flag 'l'.

The combined variable string comparison and condition truth
boolean is effectively a string comparison, with the added power
of the extra substring and ~Fpattern match~E condition codes. The
'xstring' forms the parameter for an implicit ~FTest variable~A
action, with 'x' being a variable and 'string' being a comparand.
The condition codes are set accordingly, and the boolean returns
the truth of the specified condition code 'c'.
~G
For a boolean expression, the 'n' condition code is set for a TRUE
result and a 'e' condition code for a FALSE result (this may seem
counter intuitive at first). The ~FQuick conditional~E expression
testing action can be used for convenient testing of boolean
expressions.

The triadic conditional choice expression is of the form:-

  expr?true expr:false expr

e.g.

  a<3?45:78

    - if variable a less than 3 return 45 else return 78

Each expression may be of the full expression form. Nested triadics
are therefore possible, but should be enclosed in parentheses.
.
.FRAME String Functions
.TITLE Modifier code &
~X1Format:     &FParg

There are a number of functions which return a string or a number.
In the general form shown above, 'F' is the function code, 'P' is
an optional parameter and 'arg' is the argument string to apply
the function against.

~X1[1]    ~FList of string functions~PA@C4Function~K1~E
.
.FRAME ASCII value of character
.TITLE Function code A
The 'A' function returns the ASCII value of the first character of
the remaining string, and is the same as the BASIC ASC() function.

   &AA

returns '65', as this is the ASCII decimal code for 'A'
.
.FRAME Nth frame
.TITLE Function code a
Format:  &annn

The '&a' function returns the name of the nnnth frame in the
current hyperfile.

eg.

      F&a12               - display 12th frame in hyperfile
.
.FRAME Scale number
.TITLE Function code B
The 'B' function is used to format numeric variables for
display with decimal places. It takes the next character
as the number of decimal places to display.

  &Bpvalue

returns 'value' with 'p' decimal places.

  &B212345       -  returns 123.45

  &B312          -  returns 0.012
.
.FRAME Graphic information
.TITLE Function code b [G]
Format:  &bc

The b function gets graphic information at the pixel resolution.
The parameter c can have the following values:-

     x     graphic x coord
     y     graphic y coord
     X     mouse x coord
     Y     mouse y coord
     M     current mode (as set by ZM action)
     C     character cell height
.FRAME Character of code
.TITLE Function code C
The 'C' function returns the character equivalent to the ASCII
value provided by the remaining string, which is expected to be
numeric, and is the same as the BASIC CHR$$() function.

   &C66

returns 'B', as this is the character with ASCII code 66
.
.FRAME External function
.TITLE Function code c
The 'c' function passes its argument to a Resident Extension,
if there is one installed, and returns the result string.

For example, using the hrxfp floating point extension

  &c10/4          returns 2.5
.
.FRAME Display adaptor code
.TITLE Function code D
The 'D' function returns a single digit representing the type
of display adaptor currently in use. Codes returned are:-

0       CGA adaptor
1       Monochrome or Hercules adaptor
2       EGA adaptor
3       VGA adaptor

This ~sbutton~E displays the current monitor type
.
.SCRIPT button
VT&D
VT=T+1
P@mAdaptor($T)
.
.MENU Adaptor
CGA
Monochrome
EGA
VGA
.
.FRAME String of character
.TITLE Function code 'd'
~X1Format:    &dxnn

The 'd' function returns a string of length nn containing
character 'x's.

   eg. to return a string of 15 equals signs:-

   Ve&d=15

This could be used for a number of purposes, for instance
in a frame display to show a bar graph representing the
values of variables:-

   People     : $(&d#$p)

if variable p contains 12, this would display as:-

   People     : ############
.FRAME Extended key mapping
.TITLE Function code E
This function works as for the ~FM function~PFString mapped to key~E.
The extended mapping function &Eks should be used for function
key mappings, as 'ks' is specified as for action K.

    &EF8

returns the action string mapped to function key 8
.
.FRAME Edit text
.TITLE Function code e
~X1Format: &enn

The 'e' function permits the text on the screen at the current
text cursor location, of length nn, to be edited for input,
the result being returned.

This function is intended for specifying dynamic form fill
fields.

For example, to put a prompt on the screen and then input
a string, allowing a default, the following actions are used.

   i~~X10~~Y15Name : ~~DI$n~~W20~~X17~~c;Vn&e20

Note that ~~c is used to keep the text cursor on the same line.

CAUTION: This function should be used with care
.
.FRAME Substring from
.TITLE Function code F
The 'F' function takes the next character as a search argument, and
returns the substring from, and including, the located character,
or the full string if this is not found.

   &Fdabcdefg

returns 'defg', as this is the part of 'abcdefg' starting with 'd'
.
.FRAME Get key with timeout
.TITLE Function code G
The 'G' function takes the supplied numeric string as a
timeout period in hundredths of a second. It then awaits
a key depression and either returns the character pressed,
or a null string if the timeout occurs. The character can
be fed back as key input using the ~FUnget key code~E
action, for use in selections from frame displays etc.

   Vn&G300         - this waits 3 seconds for a key press
                     and loads it into 'n', or times out.
.
.FRAME Get text from screen
.TITLE Function code g
Format:     &gnn

The 'g' function returns the text of nn characters from the
current text cursor position.

This can be used with the other direct input and output
commands (~FInsert text~E and ~FInput from screen~E) to copy text
from the screen for use elsewhere.
.
.FRAME Time of day
.TITLE Function code H
The 'H' function returns the time of day as hundredths of
a second. This can be used to time long periods of activity.
Short periods can be timed using the ~FDelta time~E function.

   &H

returns time of day.
.
.FRAME Add matching frames to notepad
.TITLE Function code 'h'
~X1Format:    &hcomment

The 'h' function adds all frames matching the last search to
the notepad list, with comment 'comment'.

    eg. Y&hSecond set

The function returns nothing of value.
.FRAME Index of character
.TITLE Function code I
The 'I' function takes the next character as a search argument, and
returns the index of this character within the remaining string, or
zero if it is not found. This is similar to the BASIC INSTR()
function, but only deals with a single character search argument.

   &Icabcdef

returns '3', as 'c' is the third letter in 'abcdef'
.
.FRAME Input from screen
.TITLE Function code i
~X1Format: &i{default}

The 'i' function permits a string to be input at the current
text cursor location, with an optional default value supplied.

This function is intended for direct screen I/O in conjunction
with the 'i' action, and possibly with windows defined using
the ~~b2 and ~~b3 flags.

For example, to put a prompt on the screen and then input
a string, allowing a default, the following actions are used.

   i~~X10~~Y3Enter name: ~~c
   Vn&iFred

CAUTION: This function should be used with care
.
.FRAME Delta time
.TITLE Function code J
The 'J' function returns the time since the last call to
function 'J', function 'G', function 'H' or the last frame
display in hundredths of a second. It can be used to time
certain events, such as the time taken to select from a menu
or a frame.
.
.FRAME Frame index
.TITLE Function code j
Format:  &jframe name

The '&j' function returns the index of the named frame in the
current hyperfile.

eg.

      &jintroduction      - returns 1 ('introduction' is first frame)
.
.FRAME Prompted key input
.TITLE Function code K
The 'K' function takes the remaining string as a popup message,
awaits a key depression, and returns the character for the key
pressed. This is similar to the BASIC INKEY$$() function.

   &KPress Y or N

could return 'Y' or 'N' (or any character typed in response)
.
.FRAME Clear local flags globally
.TITLE Function code k
~X1Format:    &kc

The 'k' function code clears the local flag given as argument
in all frames in the current hyperfile.

   eg. Y&k/     clear search match flags
       Y&k2     clear local flag 2 in all frames

The function does not return anything useful.

.FRAME Length of string
.TITLE Function code L
The 'L' function returns the length of the remaining text string in
the action, and is the same as the BASIC LEN() function.

   &Labc

returns '3', as there are three letters in 'abc'
.
.FRAME Length of hyperfile
.TITLE Function code l
Format:  &l                                 (HI.EXE ONLY)

The '&l' function returns the length of the current hyperfile.
.
.FRAME String mapped to key
.TITLE Function code M
The 'M' function takes the next character as a key character, and
returns the string mapped to that character (using the 'K' action),
or a null string if nothing is mapped.

   &Mh

could return 'NHelp', if the mapping action 'K#hNHelp' was in effect
.
.FRAME Name given title
.TITLE Function code m
Format:  &mstring

The '&m' function returns the name of the frame with a title
containing 'string'.

eg.

      &mstructure        - returns 'File contents' (in HSREF.HYP)
.
.FRAME Indexed character
.TITLE Function code N
The 'N' function takes the next character as a numeric argument
specifying an index into the string. The character indexed in the
string is returned as the result of the function.

   &N4abcdef

returns 'd', as this is the 4th letter of 'abcdef'

Functions &u, &S and &N can now have a single letter variable name
specified in place of the single digit position (length) field.  The
contents of the variable are then used as the position (length), and
can exceed the limit of 9 otherwise enforced by the single digit.
eg.  to return the 15th character of a string:-

  Vx15
  Vc&Nxabcdefghijklmnopqrstuvwxyz
      ^--- variable x contains 15, therefore 15th character returned
.
.FRAME Frame page number
.TITLE Function code n
The '&n' function code returns the current page number of the
current frame.

This can be used to log the current position in the frame.

Eg. for a three page frame, on the third page,

     Vp&n       stores 3 in variable p
.
.FRAME Application option setting
.TITLE Function code O
The 'O' function takes application flag specification following
and returns the character mapped to that flag.

     &OA

would return the character setting of flag 'A' (set via action O*A)
.
.FRAME Attribute value of scheme
.TITLE Function code o
~X1Format:    &oX

Function 'o' returns a numeric value associated with colour
scheme X.  This value represents the colour attributes for the
scheme and may be used in the revised scheme setting action,
which can accept a numeric value. Thus, it is possible to save
the colour settings as a file which can be used as a script to
restore the settings.
.FRAME Pick word
.TITLE Function code P
The 'P' function returns the word or number over which the mouse
cursor is positioned. This can be used for direct selection or
prompted selection of words. If any character follows the &P,
the word is echoed at wherever the text cursor is positioned.

    K#nN&P

When the 'n' key is pressed with the mouse positioned on a word,
this pops up a global note, if there is one, about the word.

    pSelect word to search for
    P
    A@S&P

This prompts for the selection, issues a null popup message
to await mouse selection with any key, then searches for the
selected word in the frame titles.
.
.FRAME Typed file details
.TITLE Function code p
Format: &pn

The 'p' function returns details about the current or previous
file which was typed using the ~FDisplay text file~E action.

The parameter 'n' may have the following values:-

    0 - returns 1 if file still available, else 0
    1 - returns current page number ?
    2 - returns current maximum page number ?
    3 - returns end of file page number or 999 if not reached ?

See Also: ~FTyped file name~E
.
.FRAME Pick reference
.TITLE Function code Q
The 'Q' function returns the action string for the reference over
which the mouse cursor is positioned, or a null string if not
over a reference. This can be used for processing the action in
other ways than executing it, when selected using a key other
than the Return key.

    &Q            - returns the reference action

    &Qn           - return first n characters of action

    The &Q function can have a single digit length field added, which
    restricts the returned value to the specified length. This is for
    use in the help message line system described elsewhere.
.
.FRAME Run option
.TITLE Function code R
The 'R' function returns the numeric value of one of the run
~FOptions~E or ~FExtended Options~E. It takes a numeric parameter
equal to the option number (plus 10 for extended options).

    &R17                  - returns the tab stop width.

    &R4                   - returns the autoreference setting

Also for codes 20 onwards:-

 20 returns 1 if -s was specified on the command line
 21 returns 0 if -m was specified and 1 if not.
 22 returns the number of input files open using 'r'
 23 returns the number of output files open using 'w'
 24 returns 1 if U.K. date format, 0 if U.S. date format
 25 returns the number of frames listed in the
                last search operation or contents list
.
.FRAME Read position
.TITLE Function code r
The 'r' function returns the byte position in the current input
file. This can be used to provide a direct access mechanism
using the !P function to subsequently position here.
.
.FRAME Substring indexed
.TITLE Function code S
The 'S' function takes the next character as a numeric argument
specifying an index into the string. The substring indexed in the
string is returned as the result of the function. This is similar
to a variant of the BASIC MID$$() function.

   &S4abcdef

returns 'def', as this is the substring starting at the 4th
character of 'abcdef'.
.
.FRAME Local flag mask
.TITLE Function code s
Format:  &sframe name

The '&s' function returns the local flag mask of the named frame
in the current hyperfile.

eg.

    &sintroduction      - returns the mask for frame 'introduction'
.
.FRAME Frame title string
.TITLE Function code T
The 'T' function takes the remaining string as a frame name, and
returns the title string for that frame.

   &TFrame title string

would return 'Function code T'
.
.FRAME Typed file name
.TITLE Function code t
Format: &t

The 't' function returns the filename of the current or previous
file which was typed using the ~FDisplay text file~E action.

See Also: ~FTyped file details~E
.
.FRAME Substring upto
.TITLE Function code U

The 'U' function takes the next character as a search argument,
and returns the substring up to, but not including, the located
character, or a null string if this is not found.

   &Udabcdefg

returns 'abc', as this is the substring of 'abcdefg' up to,
but not including, the letter 'd'.
.
.FRAME Upto nth character
.TITLE Function code u
The 'u' function takes the next character as a length,
and returns the substring up to, and including, the length
specified, or the whole string if it is shorter than n.

   &u4abcdefg

returns 'abcd', as this is the first 4 characters of 'abcdefg'.
.
.FRAME Configuration string value
.TITLE Function code V

The 'V' function takes the numeric argument as a ~Fconfiguration~E
string index and returns the string configured to that value

     &V56

would return the date format string
.
.FRAME Variable address
.TITLE Function code v
~X1Format:  &vx

The 'v' function returns a string representing the segment and
offset address of the variable 'x', in a form usable by an
external program, so that the variable may be accessed.

The form of the string is two hexadecimal numbers separated by
a colon, as follows:-

    SSSS:OOOO

This string can be assigned to a variable and used in a command
line of an invoked program. This can then access and modify the
variable if it decodes the address first. If a variable is to
receive data, it must be large enough for that data, otherwise
information will be overwritten, with unpredictable results.

CAUTION: This function should be used with extreme care
.
.FRAME Whole string
.TITLE Function code W

The 'W' function returns the whole supplied string.

This is used to permit action modifier characters to be included
in the initial few characters of action strings.

     P&W?Hello

would popup the string '?Hello'

whereas

     P?Hello

would prompt for a string with 'Hello' and then pop it up
.
.FRAME Details of last reference selected
.TITLE Function code w
~X1Format:    &wn

Function w returns details of the last reference selected.
The argument 'n' can have the following values:-

      0 - ASC val of reference type
      1 - ref start column
      2 - ref line number
      3 - ref column after end
      4 - ASC val of key mapping
      5 - [G] depth of reference in character rows

For notes, column and line positions are for whole screen,
and not relative to top left of note.

Results are unpredictable if a reference has not been selected.
.FRAME Graphic X coordinate
.TITLE Function code X
 The 'X' function returns the column number of the mouse
 cursor when a button was pressed during the last graphic
 display.
.
.FRAME Text cursor column
.TITLE Function code x
The '&x' function returns the current text cursor column.

The text cursor is used to write text to the screen, and is
affected by frame and note displays, and by the ~FInsert text~E
action.
.
.FRAME Graphic Y coordinate
.TITLE Function code Y
 The 'Y' function returns the line number of the mouse
 cursor when a button was pressed during the last graphic
 display.
.
.FRAME Text cursor line
.TITLE Function code y
The '&y' function returns the current text cursor line.

The text cursor is used to write text to the screen, and is
affected by frame and note displays, and by the ~FInsert text~E
action.
.
.FRAME Graphic key press
.TITLE Function code Z
 The 'Z' function returns the key pressed during the last
 graphic display.
.
.FRAME Details of last graphic
.TITLE Function code z [G]
~X1Format:     &zc

Function &zn returns information about the last graphic displayed
using the ZZ or reference variants of the graphics sublanguage, or
popped back from a popup item. The parameter n is an index into the
graphic image header.

    &z0 - should have a value of 127
    &z1 - character cell depth for image (8,14 or 16)
    &z2 - left column  \
    &z3 - top row      / These give the top left corner position
    &z4 - width in character cells
    &z5 - depth in character cells
.FRAME Convert string
.TITLE Function code #
~X1Format: &#vconv

The function '#' performs string conversion on the variable
'v' according to the conversion string 'conv'.

The conversion string is taken as a string of directives to
show the conversion required. Directives can be as follows:-

    l      - convert to lowercase
    u      - convert to uppercase
    s      - strip superfluous spaces
    tv     - translate according to variable v
    rv     - remove characters in variable v

each directive can be made conditional by preceding it with:-

                      ic

where c is any condition code letter

   e.g. i3rr removes characters specified in variable 'r' if
        frame-local flag 3 is set

directives and conditional directives can be combined in a
single string:-

  e.g.  ls        - convert to lowercase and remove spaces

So, to convert variable x to lowercase and remove spaces:-

           Vx&#xls

The conversion string can be supplied from a variable simply
by using a variable token.

  e.g. to use the '~~' variable, the action is:-    Vx&#x$$~~
.
.FRAME Dynamic menu functions
.TITLE Modifier code @
~X1Format:    @menuspec

The dynamic menu specification covers a range of menus and paged
selections. The selected choice from the dynamic menu becomes the
resulting string.

These menus are not necessarily 'dynamic', but the term does apply
to some of them, and is used collectively for all of them.

~X1[1]    ~FList of dynamic menus~PA@C4Menuspec~K1~E
.
.FRAME Select backtrack
.TITLE Menuspec B and b
The '@B' dynamic menu presents a paged list from which a frame
can be selected, and returns the backtrack level number. This is
usually used with the 'b' action to unwind to a frame:-

    b@B

The following action will unwind fully to the entry frame

    b1

The '@b' dynamic menu presents a paged list from which a frame
can be selected, and returns the frame reference. This is usually
used with the 'A' action to revisit a frame without unwinding the
backtrack list:-

    A@b
.
.FRAME Contents list
.TITLE Menuspec C
The contents list menu '@C' presents a paged list of frames in the
current hyperfile, optionally refined using the variants shown below.
The contents list returns a frame selection action, and is usually
used with the 'A' action:-   A@C

@C0     Is the same as @C, and lists all frames in the hyperfile
@C1     Lists those frames matched in the last search
@C2     Lists those frames not matched in the last search

@C0, @C1 and @C2 can also have a string appended which is used to
refine the list to those frame names starting with the supplied string.

@C3string   Lists all frames starting from the first frame name
            starting with 'string'
@C4string   Lists all frames with titles starting with 'string'
@C5string   Lists all frames starting from the first frame with
            a title starting with 'string'
   @C4^string and @C5^string do pattern match of string in title

A@C3$$1     - lists all frames starting at the current frame
.
.FRAME Formatted list
.TITLE Menuspec G
~X1Format:    @Gfilename{#page}{/search}

This is a variant of the ~FDisplay text file~E action, and is used for
producing formatted listings of files with special character
separated fields, for instance comma separated fields. The line to
be displayed is firstly split into a number of variables, then a
format line with embedded variable tokens is expanded and
displayed. The parameter specification, and the operation of the
list is as for the ~FDisplay text file~E action. Any comparisons for
searches are done done against the original line.

The ~AG mappings~PFGeneral mapping~E need to be set up before using the @G list.

KG5    variable split specification
KG6     selection expression
KG7    line format template, with variable tokens and
        two  %c tokens for key mapping
~G
The G5 mapping should be a variable split specification, as for the
~FFormatted read~E action, and will cause each line to be split into
the specified variables before display.

eg. KG5,abcd   - split line on commas into variables a, b, c and d

The G6 mapping is a 'selection expression'. This is an expression
as used in the ZI action. The variables set up by G5 can be tested
to provide a selection of records to be displayed.  If the
expression is true, the formatted line is displayed, otherwise the
record is ignored. Note that it is set to 1 by default as this is
true for all records, so this key mapping need not be explicitly
set. This expression is particularly effective with numeric fields,
and can be used with combination string comparisons for more power.

eg. KG6(a > 0) & (a < 11)

display only those records with field 'a' between 1 and 10.
~G
The G7 mapping is a prototype line which is used to format the
variables and to provide an optional key mapping if reference
flags are added. Two %c tokens can be included, which will receive
the key map characters as used in other paged displays. Note
double dollars are used in the mapping line to delay expansion
until the display stage. Examples:-

KG7$$$$a~~C20$$$$b~~C40$$$$c~~C60$$d

- Simple tabulated list of variables a, b, c, d

KG7[%c]  ~~A$$$$a~~PSprocess($$$$a)~~K%c~~E ~~C40$$$$b~~C50$$$$c~~C60$$$$d

- Key mapped list with variable 'a' set as a reference to a script
  called using the value of 'a' as a parameter.
.
.FRAME Directory listing
.TITLE Menuspec D, d and E
~X1Format:    @Dwildcardspec

The '@D' menu pops up a menu of files matching the wildcardspec,
and returns the filename selected. No extension is displayed in
the menu, and no extension is returned.

The '@d' works as for the '@D' menu, only the file extension is
included in the menu, and is returned on selection.

The '@E' works as for the '@D' menu, only the menu presented
only includes subdirectories.

The menu return can be used in any action, or dynamic menu,
requiring a file specification as a parameter.

      T@d*.TXT       - gives a menu of files with extension .TXT
                       then displays the file selected

      C@E*.*         - change to selected directory
.
.FRAME Popup menu
.TITLE Menuspec M,m and F
~X1Format:    @Mmenuname
      @Ffilename

The popup menus simply present the menu named, and return the
option selected.

The '@F' menu uses the contents of a file as the menu.
The filename specified has a default extension of '.MNU'.

     Vp@Fprice           - uses PRICE.MNU as a menu
.
.FRAME Extended directory
.TITLE Menuspec L and l
~X1Format:     @Lwildcardspec
       @lwildcardspec

The extended directory display '@L' presents a paged list
showing details of the files matching the wildcardspec, in
a similar fashion to the DOS DIR command. It returns a filename,
and should be used with an action requiring a filename parameter.

     G@L*.PIC        - lists all files with an extension .PIC

The extended directory display with actions added '@l' provides
its own action strings for typing a text file or changing to a
directory, and should be used with the 'A' action.
.
.FRAME Popup note
.TITLE Menuspec N,n and t
~X1Format:     @Nnotename
       @tfilename

The popup note displays return the action string resulting from
selection of a reference within the note display. These do not
have to be used as actions, and a note can be used as a fancy
form of menu which can return any string for any purpose.
.
.FRAME Variable menu
.TITLE Menuspec O
~X1Format:    @Oxxxxx

The named variable popup menu is formed by the set of variables
starting 'xxxxx'. This may be used to produce a menu at runtime
from miscellaneous data.
eg.
       ZVnames0=Select name
       ZVnames1=Henry
       ZVnames2=John
       ZVnames3=Simon
       ZVnames4=Albert
       VN@Onames

       This builds a menu and presents it for selection, loading
       teh result into variable N.
.
.FRAME Notepad selection
.TITLE Menuspec R
~X1Format:     @R

The notepad display '@R' is used to display a paged list
showing the noted references and their associated comments,
and returns the selected reference action, it is usually
used with the 'A' action:-

     A@R
.
.FRAME Search selection
.TITLE Menuspec S,s,X and x
~X1Format:    @Ssearch string

The search operations available are as follows:-

    Sstring      Search for string in titles of current file
    sstring      Search for string in titles of open files
    Xstring      Search for string in titles and texts of current file
    xstring      Search for string in titles and texts of open files

The title searches look for the search string in the frame name
and the title. A search string starting with the '^' character
indicates that a ~Fpattern match~E search is to be performed, and that
the remaining string forms the pattern. The search menus normally
return a frame selection action, but may also return other reference
actions. They should be used with the 'A' action:-

    A@S?Enter search string

The list of matches produced can be used for immediate selection,
or can be left to complete and subsequent selection made from a
restricted contents list:-

     A@C1

The search can be restricted to refine a previous search or to
add to a search. This is achieved by setting the search refinement
option O*6 as follows:-

   O*60       Search all frames
   O*61       Search frames matched in last search
              This refines the search (effectively an AND)
   O*62       Search frames not matched in last search
              This adds to the matched frames (OR condition)
   O*63       These work as for 1 and 2, but reset the option
   O*64             to 0 after the next search operation.

When an additive search is done, only the new matches are shown
in the search listing. A subsequent restricted contents list as
above will show all the matching frames.

If the option O*6 has 5 added to its value, the search listing
only shows the first page of lines matched, does not list the
frames for selection, and returns immediately the search is
complete or the user presses a key to abort the search. The
value of 5 is subtracted from the option value at the start of
the search, and the remaining value is used as indicated
above.

This feature is provided to allow combinations of searches to
be performed without user intervention, such as looking for
frames containing 'string a AND string b' or 'string a OR
string b'. Combinations of title search and text search should
start with the title search, as this will reduce the amount of
text searching required. The last search can be a normal
stopping search so that selection can be made from the
listing.
~G
By clearing option flag O*82, the matching line will not
be displayed.

By setting option O*84, search conjunctions can be supported
comprising simple conjunctions on one line. The format of
the search string in this case takes the following form:-

stringa!stringb           stringa or stringb on a line
stringa&stringb           stringa and stringb on a line
stringa!stringb&stringc   stringa or (stringb and stringc) on a line

Combinations of '&' (and) and '!' (or) can be used to specify
complex search conditions.
.
.FRAME Pattern strings
.TITLE Action suffix |
The pattern string may be optionally specified after an action
modifier to format the return string into a form expected by the
action. Pattern strings consist of the string expected as a
parameter, with all occurences of the chosen string represented
by the string '%s'. Up to three occurrences of the chosen string
may be expanded in the pattern string. An example is a command
to copy a file selected from a directory display to the root
directory of drive C:-

   d@d*.*|COPY %s C:\%s

This facility can be used for more complex formatting, if the
variants on the '%s' format token are used:-

    %{-}{nn){.mm}s
      |  |    |
      |  |    maximum length (truncated at right end)
      |  minimum length (right aligned, space fill)
      left align (else right align)

 For example:-

    %s    full string as supplied
    %8s    string to minimum length of 8, right aligned
    %-8s        ditto, left aligned
    %.23s    string to maximum length of 23

For example, to shorten a variable, x, to 5 characters, and
enclose it in square brackets (function &W is used here):-

   V&W$$x|x[%.5s]

This facility is useful where you are formatting lines for
printout, to make things line up in columns.
.
.FRAME Paged displays
.TITLE Lists presented page by page
Paged displays provide a full screen display offering one line per
option, and offering multiple pages of options if necessary.

F1 or ?    - Help menu
F2 or #    - Go to page number (*T)
F3 or PgUp - Previous page
F4 or Home - Start of list/file
F5         - Find next match (*T)
F6 or /    - Search file (*T)
F7         - Redisplay page (*T)
F8 or End  - End of file (*T)
F9         - Quit (*T Suspend list)
F10        - Quit (*T Quit list)
Return     - Select reference (*T Suspend if not on reference)
INS/DEL    - Add / Remove reference from notepad

(*T - Type file control keys)
.
.PRINT SECTION 6.
.
.PRINT TITLE
Reference Guide - Variables
.
.PRINT PAGE
.
.FRAME Variables
.TITLE Section - containers for data
HyperShell permits strings to be assigned to 'variables'.
These are token characters which hold character or numeric data
strings and can be expanded anywhere in the displayed text, and
can also be used to parameterise the control strings of the
various ~Factions~E that may be performed.

There are three main types of variable:-

~X1[1]    ~FSystem variables~K1~E - used for HyperShell details

~X1[2]    ~FApplication variables~K2~E - used by applications

~X1[3]    ~FNamed variables~K3~E - extra applications storage
.
.FRAME System variables
.TITLE Variables about HyperShell itself
There are a number of system variables, some of which may be
set by hyperfile applications, and some which can only be expanded.
The HyperShell system variables have the names '0' to '9' and some
special characters, and have the following string values:-

 0      full pathname of HyperShell program used
 1      current frame name
 2      current frame title
 3      current file name
 4      current date
 5      current time
 6      backtrack list current depth
 7      current directory
 8      original directory
 9      HyperShell name and version
 ?      error code of last error that occurred
 <      file name returned from last paged directory display
 >      filename extension returned from last long directory
 :      list of extensions to be excluded from TYPE action
 @      Available memory
 _      File prompt (becomes null string when viewing file)
 ^      Exit status from X,x,D,d action program execution
 \      Parameter supplied in parentheses to note or script
 `      Error action - action taken on error status set
 ~~      Variable specifying string conversions for comparisons
 ,      Pseudo variable - represents ';' in action mappings
 !      Pseudo variable - represents '!' in action mappings

The ':' variable is a string representing those file extensions
for which the extended directory display providing actions
(dynamic menu 'l') will not set a 'Type file' action. It is set
to the following string by default:-

   .EXE.COM.OBJ.SYS.DBF.LIB.

Additional extensions can be added by resetting the variable.
Note that extensions should have a '.' to each side.
.
.FRAME Application variables
.TITLE Variables with single character names
Application variables are strings that may be stored under a
single letter name, either upper or lower case. Thus there can
be 52 application variables. Variables can be set within a
hyperfile and may be 'expanded' within the frame text or in an
action string.

Application variables are provided to allow a hyperfile to modify
its behaviour depending on circumstances. For instance, variables
may be used to input parameters one at a time in order to build
up a command line for execution under DOS, or to build an action
specification. Popup menus are useful for setting variables to
one of a fixed set of values.

In addition, an unlimited set of ~FNamed variables~E are available,
which provide for longer term storage of data, and for sets of
data in pseudo-arrays.
.
.FRAME Expansion of variables
.TITLE Variable token specification
The variable expansion token for system and applications variables
takes the form '$$x' where x is the variable name. This is expanded
to the string value of the variable.

The variable may be expanded in the frame text, in a note text, or
in an action string, where it may form any part of an action string
apart from the action code itself (although the 'A' action can be
used to permit the expansion of a variable to an action code).

The variable expansion token is simply the flag character $$
followed by the variable name character. e.g. :-

   $$a

If the '$$' symbol is required in the text, two '$$' symbols together
will be taken to mean one, which will not be expanded when the text
is displayed, or when an action string is expanded prior to execution.
This may be used when an action string in a reference in frame text
needs to contain a variable expansion token itself, but this must
not be expanded until the action is performed.
.
.FRAME Named variables
.TITLE Variables for longterm use
There are another set of variables which can be specified. These
are set and expanded in a different manner to single character
~Fvariables~E. They are set using the ~FLoad named variable~E action or
the ~FSet Named Variable~E action.

Named variables are expanded using the form:-

   $$(name)

Where 'name' is the name of the variable. The name can be specified
by a string containing single character variable expansion tokens,

~X1Example:

   $$($$n)  or   $$(item $$n)   or   $$($$n$$m)    etc.

Where n is a single letter variable containing the name of the
named variable. This feature can be used for pseudo-arrays with
a limited form of 'subscripting', or indirection.
~G
It is possible to include a single character variable expansion
token within the named variable value string. This will be expanded
when the named variable is expanded.

~X1Example:

ZVtime=Time: $$$$5

This will expand to the current time in the form 'Time: hh:mm:ss'
when specified in text as $$(time).

~X1Inline action modifier

Special forms of the named variable token can be used to
cause inline expansion of certain action modifiers. The
modifiers supported are as follows:-

  $$(&nnnn)      - return value of ~FString functions~E
  $$(=nnnn)      - result of ~FExpression evaluation~E
  $$(%nnnn)      - DOS ~FEnvironment Variable~E value

~X1Examples

  $$(=a+b)    - would expand to the sum of variables a and b.

  $$(&L$$b)   - would expand to the length of variable b

  $$(%HSPATH) - would expand to the setting of HSPATH
.
.PRINT SECTION 7.
.
.PRINT TITLE
Reference Guide - Conditions
.
.PRINT PAGE
.
.FRAME Conditions
.TITLE Section - Condition codes and flags
HyperShell provides a general system of condition codes which
can be used to control various aspects of display and execution.
The condition code token is a single character, which is
specified in ~Fconditional action~Es, ~FHidden lines~Es and also
in ~Fmenus~E.

The condition code has a number of potential values:-

~X1[1]     ~FResult of test~K1~E - for variable tests

~X1[2]     ~FError status~K2~E - for action errors

~X1[3]     ~FReturn value~K3~E - for action modifier returns

~X1[4]     ~FLocal flags~K4~E - for frame related control

~X1[5]     ~FGlobal options~K5~E - for application options
.
.FRAME Result of test
.TITLE Condition set by test
The traditional use of a condition code is to determine the result
of a test or comparison. The first set of codes are used for this
purpose, and are set up by the ~Ftest variable~E action 'v'. The test
conditions available are as follows (note the lowercase form is used)

   e      variable equals string            *   !
   n      variable not equal to string          !
   g      variable greater than string      *   !
   l      variable less than string         *   !
   d      variable is defined
   u      variable is undefined
   c      variable contains string
   w      variable is contained within string
   m      variable matches a pattern            ~~
   f      variable fails a pattern match        ~~

~G
Note that the conditions marked with an asterisk indicate lexical
comparisons unless the comparand string starts with a numeric
digit or a minus sign '-', in which case an arithmetic (integer)
comparison is made.

The condition codes marked with an exclamation point are also set
by use of the ~Fexpression evaluation~E function '=', indicating
how the result compares against zero. e.g. 'g' is set if the
result is positive.

The condition codes marked with a ~~ are only set if a pattern
match is performed, due to the variable '~~' being set. Code
'f' is otherwise always set.
.
.FRAME Error status
.TITLE Condition set by error
The next set of codes are used to indicate whether the error
status is set, as follows:-

   s      the error status is set
   o      the error status is O.K. (clear)

The error status can be cleared to 'O.K.' by the action 'Y', and
will otherwise retain its setting, even if successful actions are
performed.
.
.FRAME Return value
.TITLE Condition set by action modifier
This set of condition codes are used to determine whether a
string is returned from ~Faction modifier functions~E, or whether
a null string was returned or the function cancelled.

   r      a string was returned
   b      a blank string was returned or the function was
          cancelled

These are very useful for a number of purposes, for example
to determine whether a selection has been made from a menu or
a string has been input to a request, or that a timeout has
occurred from a ~Fget key with timeout~E function.
.
.FRAME Special codes
.TITLE Condition codes for variants
A special set of condition codes are provided with the variants of the
base HyperShell, to allow a hyperfile to determine which program is
running and whether an item is being edited or viewed.

      i        Integrated environment being used
      v        Item is being viewed, not edited

      x        Graphic versions eg. HG.EXE, HGI.EXE etc
.
.FRAME Local flags
.TITLE Condition codes local to frame
This set of condition codes are flags which are local to each
frame. These are usually used to flag a matching frame after a
~Fsearch selection~E, or to control ~FHidden lines~E in frames and
notes. They are set using the ~FLocal flag toggle~E.

   0 to 9     frame local flag.

   :          visited frame flag (set after frame visited)
   /          matching frame flag (set by searches)
   <          frame more than one screen
              this is set after display of first screen of
              frame text, but is available in the footer and
              on subsequent screens and visits to the frame.
.
.FRAME Global options
.TITLE Condition code for global control
The fourth set of condition codes represent a set of general
control flags which may be used to control a hypertext application
- the ~Fapplication options~E. These flags are set using the
~Foption setting~E action O*X and are as follows:-

  A to Z      application options

These flags are character flags which evaluate TRUE if they are set
to other than a null character.
.
.PRINT SECTION 8.
.
.PRINT TITLE
Reference Guide - Restrictions
.
.PRINT PAGE
.
.FRAME Restrictions
.TITLE Section - limits and reserved chars
This section contains:-

~X1[1]    ~FSize limits~K1~E

~X1[2]    ~FNumber Limits~K2~E

~X1[3]    ~FReserved characters~K3~E
.
.FRAME Size limits
.TITLE Maximum lengths
Line size, including flag characters, expanded variables etc. is
limited to 255 characters.

Frame name may be up to 35 characters.

Title length may be up to 40 characters.

Reference text length may be up to 39 characters.

Action strings may be up to 40 characters, or 79 in scripts.

Frame text can be up to 80 characters wide.

Frame text can be any number of lines deep although the recommended
limit is 24 - (header lines + footer lines).

Note, Script and menu names must be less than 35 characters.

Note text can be up to 76 characters wide and 22 lines deep, extra
text being truncated.
.
.FRAME Number limits
.TITLE Maximum counts
There can be up to 100 references per displayed screen, INCLUDING
headers and footers, and any note popped up containing references.

A menu can now be any length, but will be displayed in groups of
20 options. A very large menu will exhibit a delay when showing
later options.

A script can contain up to 200 lines.
.
.FRAME Reserved characters
.TITLE Control characters
The following characters cannot appear within the second (or
third if the second is not one of them) position of an action
specification, apart from for their stated purpose.

    @      Dynamic menu
    &      String function
    !      Read record
    =      Expression evaluation
    %      Environment variable
    ?      Prompted input

Also, for frame selection action specification

    +      Next frame
    -      Previous frame

To include the above characters in the parameter to an action,
the ~Fwhole string~E function &W can be used to 'guard' any
special characters.

The following characters cannot appear in the body of an action
specification, apart from for their stated purpose.

   $$      Variable expansion token (code $$$$ for $$)
    |      Action modifier pattern specification
    ^      (Within frame names) Hyperfile separator
   ;      Multiple action separator
          (set up variable using &C to hold ';' character)

The following characters cannot appear within frame text, apart from
for their stated purpose.

   ~~      Reference and formatting directive flag (code ~~~~ for ~~)
   $$      Variable expansion token (code $$$$ for $$)
    .      (At beginning of line) Section flag

The '(' character cannot be used in a note or script name.
.
.PRINT SECTION 9.
.
.PRINT TITLE
Reference Guide - Codes
.
.PRINT PAGE
.
.FRAME Codes
.TITLE Section - Codes and mappings
    This section contains information about codes and setting.

~X1[1]     ~FOptions~K1~E

~X1[2]     ~FExtended options~K2~E

~X1[3]     ~FColour codes~K3~E

~X1[4]     ~FColour schemes~K4~E

~X1[5]     ~FApplication options~K5~E

~X1[6]     ~FControl key mapping~K6~E

~X1[7]     ~FError codes~K7~E
.
.FRAME Options
.TITLE HyperShell control
Option Def   Value   Meaning

0 (0) -   1 = Use restart file for notepad
          2 = Use restart file for notepad, variables and frame name
          3 = Use restart file for notepad, variables
          4 = Use restart file for variables only

1 (1) -  +1 = Symbols on menus
         +2 = First letter selection on menus (Fkeys as frame)
         +4 = Immediate (hot) menus on top line

2 (1) -   1 = Record backtrack
         +2 = Extended backtrack (to page of frame)

3 (1) -  +1 = Add hyperfile name as notepad extension
         +2 = Suppress INS and DEL key notepad action
         +4 = Always Note/Remove Frame, even when over ref

4 (0) -  +1 = Autoreference frame names
         +2 = Application specified autoreference
         +4 = Autoreference global note names
~G
Option Def   Value   Meaning

5 (0) -   1 = 'o' output to printer
          2 =    to standard text output
          3 =    to AUX device
          4 =    to output file (opened by 'w')
         +8 = suppress output of line separators

6 (0) -  +1 = Display remaining space on exit
         +2 = Swap HS.EXE (~DFNB. only HS~DT) to disk on d and D actions
              Also swap HI,HG,HDX to disk/XMS on d and D actions

7 (0) -   1 = Trace script labels
          2 = Log actions and modifiers (~DFHIDE ONLY~DT)
          4 = Log condition codes (~DFHIDE ONLY~DT)

8 (1) -   1 = Give warnings of unavailable items
          2 = Give warnings of unavailable files

9 (0) -   1 = 'T' listing gives verbatim list
          2 =   also strips 8th bit, for Wordstar files
          3 = display with flags / variables interpreted
.
.FRAME Extended options
.TITLE HyperShell control
Option Def Value   Meaning

    *0 (1) -  +1 = ESC key during popups, paged displays cancels script
              +2 = Action modifier failure cancels multiple action
              +4 = Stop ESC from pausing script

    *1 (0) -   1 = Shadow edges on popups (uses G colour scheme)

    *2 (0) -   0 = No blinking
               1 = Blink mouse cursor
               2 = Blink mouse cursor and references using TAB/BackTAB

    *3 (0) -  +1 = Suppress mouse cursor
              +2 = Use cursor left/right to select references (as TAB)
              +4 = Position mouse on first reference in new frame
              +8 = Stop mouse moving to selected reference

    *4 (1) -   0 = Restrict autoreference to typed files
               1 = Include frame texts in autoref scope
~G
Option Def Value   Meaning

    *5 (0) -   0 = Accept characters less than 128 only
               1 =    less than 176
               2 =    less than 255

    *6 (0) -   0 = Search all
               1 = Search matched frames     3 = reset after
               2 = Search unmatched frames   4 = reset after
              +5 - do 'non stop' search (+5 cleared after)

    *7 (8) -   n = Tabstop width

    *8 (1) -  +1 = Request comment on noted references
              +2 = Display matching line on text search
              +4 = Allow search conjunctions

    *9 (0) -   0 = case sensitive key mapping
               1 = case insensitive key mapping
.
.FRAME Application options
.TITLE Application hyperfile control
The application control options A to Z can be:-

Set to a character using ~FOption setting~E action O*X

   O*Fj    -  set option 'F' to 'j' (condition will be true)
   O*F     -  reset option 'F' (so condition is FALSE)

Used as a ~Fcondition code~PFGlobal options~E - A to Z

   aFPIt is set    -  popup message if option 'F' is set

Supplied using the ~FApplication option setting~E function &OX

   Vx&OF   -  set variable x to character value of option 'F'
.
.FRAME Control key mapping
.TITLE Control keys and headings
Certain control keys and headings are configurable using the
~FSet key mapping~E action 'K', as follows:-

 Mapping Default      Used for
   KH1   SELECT FILE  (for directory popup menu)
   KH2   MHELP        (for ? key in frame display)
   KH3   HELP         (name of menu for ? in paged display)
   KH4   ZC           (ESCAPE mapping)    \
   KH5   y            (HOME mapping)       \
   KH6   ZR           (END mapping)        for frame display
   KH7   y-           (PGUP mapping)        /
   KH8   y+           (PGDN mapping)       /
   KH9   B            (BACKSPACE mapping) /
   KH0   HYPERSHELL   (Control menu heading)
.
.FRAME General mapping
.TITLE Control strings
The general mappings are a further set of control mappings.
These are configurable using the ~FSet key mapping~E action 'K',
as follows:-

 Mapping Default   Used for

   KG1   ""        ENTER / LEFT button action when not over ref
   KG2   ""        ENTER / LEFT button action in ~FDisplay text file~E
   KG3   ""        ESCape / RIGHT button action in ~FDisplay text file~E
   KG4   ""        End of title for ~FDisplay text file~E and @G
   KG5   ""        Variable split specification for ~FFormatted list~E
   KG6   "1"       Selection expression for ~FFormatted list~E
   KG7   ""        Line format template for ~FFormatted list~E
   KG8   ""        ~FString input translation~E ('from' characters)
   KG9   ""        ~FString input translation~E ('to' characters)
   KG0   ""        ~FFrame transition script~E specification
.
.FRAME Frame transition script
.TITLE To set up a frame
The frame transition script specification is set using
general mapping KG0:-

  KG0sFrame transition

This causes the named script to be called on entry to
a frame, before the frame is displayed. The specification
cane be of a local script, a global script or a file
script. The specification can contain a parameter of the
form eg:-

 KG0SFTS(%c,%s)

The %s is replaced by the 'name' used to display the frame
and the %c is replaced by the 'action'.

The script is called on a frame 'refresh' as well as when
moving to a new frame, so this parameter can be used to
select new frame references only.

For example:-

  KG0sFTS(%c)

  .SCRIPT FTS
  -- Test parameter
  J&A$$\
  L102
  -- just 'f' so quit
  L70
  -- actions for 'F' reference
  .
.
.FRAME String input translation
.TITLE Mapping keys to special characters
The string input translation capability allows string input
characters to have a translation mapping applied against them.

String input is used in a number of places:-

1. For input of strings on the prompt line at the bottom.

2. For entry into input fields.

The translation converts specified character codes to other
specified character codes. This can be used for a number of
purposes, including:-

1. Stopping the input of certain characters by translating them
   to a character which is rejected, such as TAB (ASCII 9).

2. Mapping certain ALT shifted keys to accented characters for
   language learning applications. (Note: option setting O*51 or
   O*52 must be used to allow input of extended character set).
~G
~FGeneral mapping~E strings KG8 and KG9 provide the 'from' and 'to'
tables of characters. Whenever a character in the 'from' string
is input, it is translated to the corresponding character in
the 'to' string. Thus, to map the keys '%&*' to produce '!=^'
characters, the following settings are used:-

  KG8%&*
  KG9!=^

The two mapping strings must be the same length or results will
be unpredictable.

The mappings do not have any effect on single keystroke inputs, such
as function keys, menu selections, reference key mappings etc.
.
.FRAME Colour codes
.TITLE codes
Colour codes are as follows (monochrome in [brackets]):-

   K      Black [Inverse]
   B      Blue [Underline]
   G      Green
   C      Cyan
   R      Red
   M      Magenta
   Y      Yellow (brown)
   W      White (light grey) [Bright]
   k      Dark grey        (Foreground only)
   b      Light blue       (Foreground only)
   g      Light green      (Foreground only)
   c      Light Cyan       (Foreground only)
   r      Light red        (Foreground only)
   m      Light magenta    (Foreground only)
   y      Light yellow     (Foreground only)
   w      Bright white     (Foreground only)
.
.FRAME Colour schemes
.TITLE Global highlighting schemes
The available schemes are as follows, showing the scheme letter,
the default setting (foreground, background) and the normal usage.
('User' schemes are not used by HyperShell):-

   Scheme colour mono      Description

   A      wB     BK        Action reference
   B      Wk(bl) Wk(bl)    Blink
   C      KC     KW        Menu choice
   D      KW     KW        Default title
   E      yK     wK        Frame reference - replace backtrack
   F      wK     wK        Frame reference - add to backtrack
   G      KK     KK        Ghost - used for shadows on popups
   H      KY     kW        Menu heading
   I      yY     KW        Input field
   J      KG     KW        Note heading and border
   K      yG     KW        Note
   L      RK     BK        Low intensity
   M      KW     kW        Menu reference
   N      gK     bK        Note reference
   O      yB     WK        Menu selection
   P      yr(bl) Kw(bl)    Popup message
   Q      Kk(bl) Kk(bl)    XOR for reference (with TAB/BackTAB)
   R      KW     Kw        Request / message
   S      yG     BW        Script reference
   T      WK     WK        Frame text
   U      YK     BK        (User 1)
   V      MK     bK        (User 2)
   W      GK     WK        (User 3)
   X      RK     kK        (User 4)
   Y      BK     BW        (User 5)
   Z      rK     KW        (User 6)
.
.FRAME Error codes
.TITLE Status codes for error conditions
The following error codes are set in variable '?'. The variable is
only reset on command (~Fby the 'Y' action~PFClear Status~E). An action
can be specified in ~Fsystem variable~PFsystem variables~E (`), which will
be performed when the status changes from UNSET to SET (once SET,
it should be RESET using 'Y' before the action will take place again).

    0      Success - (after status cleared)
    1      Operation cancelled
    2      No choice from menu
    3      End of file when reading
    4      Cannot open file
    5      File is not open
    6      File is already open
    7      File has changed
    8      At start of backtrack
    9      Divide by 0 in expression
    10     Value not expected in expression
    11     Value expected in expression
    12     Undefined opcode in expression
    13     Unmatched parenthesis in expression
    14     Syntax error in expression
    15     Script not available
    16     Menu not available
    17     Note not available
    18     Frame not available
    19     Key not defined
    20     Invalid key code
    21     Local reference - cannot be noted
    22     Not at reference when key pressed
    23     Key not mapped
    24     No action or action disabled
    25     Invalid action code
    26     No command present
    27     Environment variable not defined
    28     Invalid dynamic menu
    29     Line too wide for screen
    30     String too long
    31     Too many lines in frame
    32     Maximum script size reached
    33     Maximum menu size reached
.
.PRINT SECTION 10.
.
.PRINT TITLE
Reference Guide - Miscellaneous
.
.PRINT PAGE
.
.FRAME General
.TITLE Section - Miscellaneous information
This section contains information on:-

~X1[1]    ~FConfiguration~K1~E

~X1[2]    ~FAutoreference~K2~E

~X1[3]    ~FAlternative Hypertext~K3~E

~X1[4]    ~FExample script~K4~E
.
.FRAME Configuration
.TITLE Changing the look and feel
The option flags, extended options and key mappings permit a lot
of configuration to be done to individual hyperfiles. The colour
schemes permit the various highlighting to be fully configured.
Custom frame headers and footers can be used to create a
professional appearance to your application.

All the prompts, headings, format strings, error messages and
other strings can also be configured using a special file called
HYPSHELL.CFG. This provides mappings between configuration
string numbers and the strings to be used. If the file is not
supplied, default strings are used. Foreign languages can be
readily supported using this. Full details are provided in the
authoring guide.
.
.FRAME Autoreference
.TITLE Inserting references dynamically
The autoreference facility adds references dynamically as the
text is displayed. A number of kinds of autoreference are
provided.

1. Frame name autoreference flags any occurrence of frame names
   in the text.

2. Application autoreferencing allows specified search strings
   to be mapped to specified actions.

3. Global note name autoreference flags occurrences of global
   note names in the text.

Both kinds of autoreference can be applied to just text
displayed using the ~Fdisplay text file~E action, or to
frame text displays as well as text files.
.
.FRAME Alternative hypertext
.TITLE Other forms of hypertext
The HyperShell single hyperfile format described in this file is
normally used for hypertext systems. HyperShell does, however,
provide a number of features which support an alternative to
this format.

The 'T' and 't' actions, described above, permit normal text files
to be displayed, and these files can contain simple embedded
references to other files, for display in a paged fashion using 'T'
or as a popup note using 't'. The authoring guide gives a
description of how this can be done.

If HyperShell is given the name of one of these simple text files,
rather than that of a normal hyperfile, it displays the file as a
single frame, possibly with multiple pages. Thus, it is not even
necessary to have a controlling hyperfile. Although it would not be
usual to do so, such a file could contain HEADER, FOOTER and global
items, provided these were supplied AFTER the main text in the
file.
.
.FRAME Example script
.TITLE to show how script works
The following script, when called with a parameter e.g.

    Slines(read.me)

counts the lines in the file whose name is supplied as a
parameter and displays the total on the bottom line.

The script is normally coded with a number of actions on
each line, but it is coded here with one action per line
so that comments can be added (these cannot appear on the
actual script).

Note that it is good practice to start a new line after a jump
or conditional jump. Labels must appear at the start of a line.

If there is an error opening the file, an error message will
have been displayed already, so we just quit. The error status
from the read is assumed to be an end of file indication. Note
that you must remember to close the file when you have finished
with it, otherwise it remains open until you quit HyperShell.~G
~C6.SCRIPT lines          - select action for details
~Fv\~PFTest variable~E                     - is there a ~Fparameter~PFparameters~E
~FjeERROR~PFjump within script~E                - no - go to error display ----\
~FVx0~PFSet variable~E                    - set count variable to zero   |
~FY~PFclear status~E                      - clear error status           |
~Fr$$\~PFOpen/close input file~E                    - open file                    |
~Fasq~PFConditional action~E                    - quit if error                |
~FLREAD~PFLabel in script~E                  - Label for read    <-------------\
~FY~PFclear status~E                      - clear error status           |  |
Vy~F!~PFRead and lookup functions~E                    - read record into variable y  |  |
j~FsEOF~PFconditions~E                  - if end of file goto display --- | \
Vx~F=x+1~PFexpression evaluation~E                 - increment count variable     |  | |
~FJREAD~PFjump within script~E                  - loop back to read  -------------/ |
~FLERROR~PFlabel in script~E                 - error display label  <-------/    |
~FPNo parameter supplied~PFpopup message~E     - display error message         |
~Fq~PFquit script~E                      - quit script  ----------------\    |
~FLEOF~PFlabel in script~E                   - End of file label    <------------/
~Fr~PFopen/close input file~E                      - close file                   |
~FpThere were $$x lines read~PFdisplay message~E          - display count    |
~C6.                      - quit script at end           v
.
.END
        End of HSREF.HYP
.